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PREFACE 


System Software Architecture 


The Amiga kernel consists of a number of system modules, some of which reside per- 
manently in the protected kickstart memory and others that are loaded as needed from 
the system disk. Figure P-1 illustrates how the various modules interact with one 
another. At the top of the hierarchy are Workbench and the Command Line Interface 
(CLI), the user-visible portions of the system. Workbench uses Intuition to produce its 
displays and AmigaDOS to interact with the filing system. Intuition, in turn, uses the 


input device to retrieve its input and the graphics and layers library routines to produce 
its output. 


AmigaDOS controls processes and maintains the filing system and is in turn built on 


Exec, which manages tasks, task switching, interrupt scheduling, message-passing, I/O, 
and many other functions. 


At the lowest level of the hierarchy is the Amiga hardware itself. Just above the 
hardware are the modules that control the hardware directly. Exec controls the 68000, 
scheduling its time among tasks and maintaining its interrupt vectors, among other 
things. The trackdisk device is the lowest-level interface to the disk hardware, perform- 
ing disk-head movement and raw disk I/O. The keyboard and gameport devices handle 
the keyboard and gameport hardware, queuing up input events for the input device to 


ili 


process. The audio device, serial device, and parallel device handle their respective 
hardware. Finally, the routines in the graphics library handle the interface to the graph- 
ics hardware. 


Programming 


The functions of the kernel were designed to be accessed from any language that follows 
the Amiga’s standard interface conventions. These conventions define the proper nam- 


ing of symbols, the correct usage of processor registers, and the format of public data 
structures. 


REGISTER CONVENTIONS 


All system functions follow a simple set of register conventions. The conventions apply 


when any system function is called; programmers are encouraged to use the same con- 
ventions in their own code. 


The registers DO, D1, AO, and Al are always scratch; they are free to be modified at any 
time. A function may use these registers without first saving their previous contents. 
The values of all other data and address registers must first be preserved. If any of 


these registers are used by a function, their contents must be saved and restored 
appropriately. 


If assembly code is used, function parameters may be passed in registers. The conven- 
tions in the preceding paragraphs apply to this use of registers as well. Parameters 
passed in DO, D1, AO, or Al may be destroyed. All other registers must be preserved. 


If a function returns a result, it is passed back to the caller in DO. If a function returns 


more than one result, the primary result is returned in DO and all other results are 
returned by accessing reference parameters. 


The A6 register has a special use within the system, and it may not be used as a param- 
eter to system functions. It is normally used as a pointer to the base of a function vec- 


tor table. All kernel functions are accessed by jumping to an address relative to this 
base. 
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Figure P-1: Amiga System Software Modules 


DATA STRUCTURES 


The naming, format, and initial values of public data structures must also be consistent. 
The conventions are quite simple and are summarized below. 


All non-byte fields must be word-aligned. This may require that certain fields be 
padded with an extra byte. 


All address pointers should be 32 bits (not 24 bits) in size. The upper byte must 
never be used for data. 


Fields that are not defined to contain particular initial values must be initialized to 
zero. This includes pointer fields. 


All reserved fields must be initialized to zero (for future compatibility). 


Data structures to be accessed by custom hardware must not be allocated on a pro- 
gram stack. 


Public data structures (such as a task control structure) must not be allocated on a 
program stack. 


When data structures are dynamically allocated, conventions 3 and 4 above can be 
satisfied by specifying that the structure is to be cleared upon allocation. 


OTHER PRACTICES 


A few other general programming practices should be noted. 


1. 


Never use absolute addresses. All hardware registers and special addresses have 


symbolic names (see the include files and amiga.l1b). 


Because this is a multitasking system, programs must never directly modify the pro- 
cessor exception vectors (including traps) or the processor priority level. 


Do not assume that programs can access hardware resources directly. Most 
hardware is controlled by system software that will not respond well to interference. 
Shared hardware requires programs to use the proper sharing protocols. 


Do not access shared data structures directly without the proper mutual exclusion. 


Remember, it is a multitasking system and other tasks may also be accessing the 
same structures. 


Vl 


5. Most system functions require a particular execution environment. For example, 
DOS functions can be executed only from within a process; execution from within a 
task is not sufficient. As another example, most kernel functions can be executed 
from within tasks, but cannot be executed from within interrupts. 


6. The system does not monitor the size of a program stack. Take care that your pro- 
grams do not cause it to overflow. 


7. Tasks always execute in the 68000 processor user mode. Supervisor mode is reserved 
for interrupts, traps, and task dispatching. Take extreme care if your code executes 
in supervisor mode. Exceptions while in supervisor mode are deadly. 


8. Do not disable interrupts or multitasking for long periods of time. 


9. Assembly code functions that return a result do not necessarily affect the processor 
condition codes. By convention, the caller must test the returned value before act- 
ing on a condition code. This is usually done with a TST or MOVE instruction. 
Do not trust the condition codes returned by system functions. 


68010 AND 68020 COMPATIBILITY 


If you wish your code to be upwardly compatible with the 68010/68020 processors, you 
must avoid certain instructions and you must not make assumptions about the format of 
the supervisor stack frame. In particular, the MOVE SR,<ea> instruction is a 
privileged instruction on the 68010 and 68020. If you want your code to work correctly 
on all 680x0 processors, you should use the GetCC() function instead (see the Exec 
library function descriptions in the ‘Library Summaries’’ appendix of this book. 


Contents of This Manual 


This manual describes the graphics support routines (including text and animation), the 
I/O devices, the Workbench (an environment for running programs), and the floating 
point mathematics library. For information about the multitasking executive, see Amiga 


ROM Kernel Reference Manual: Exec. 


The discussion of the data structures and routines in this manual is reinforced through 
numerous C-language examples. The examples are kept as simple as possible. Whenever 


possible, each example demonstrates a single function. Where appropriate, there are 
complete sample programs. 
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Boldface type is used for the names of functions, data structures, macros, and variables. 
System header files and other system file names are shown in italics. 


For more information about system software, see Amiga Intuition Reference Manual, 
AmigaDOS User’s Manual, AmigaDOS Developer’s Manual, and AmigaDOS Technical 
Reference Manual. 
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PART I 


Chapter 1 


Graphics Primitives 


This chapter describes the basic graphics tools. It covers the graphics support structures, 
display routines, and drawing routines. Many of the operations described in this section are also 


performed by the Intuition software. See the book called Intuztion: The Amiga User Interface 
for more information. 


Graphics Primitives 1 


Introduction 


The Amiga has two basic types of graphics support routines: display routines and drawing rou- 
tines. These routines are very versatile and allow you to define any combination of drawing and 
display area you may wish to use. 


The first section of this chapter defines the display routines. These routines show you how to 
form and manipulate a display, including the following aspects of display use: 


oO 


How to identify the memory area that you wish to have displayed 


How to position the display area window to show only a certain portion of a larger 
drawing area 


How to split the screen into as many vertically stacked slices as you wish 
Whether to use high-resolution (640 pixels across) or low-resolution (320 pixels across) 
display mode for a particular screen segment, and whether to use interlaced (400 lines 


top to bottom) or non-interlaced (200 lines) mode 


How to specify how many color choices per pixel are to be available in a specific section 
of the display 


The next section of the chapter explains all of the available modes of drawing supported by the 
system software, including how to do the following: 


Reserve memory space for use by the drawing routines 
Define the colors that can be drawn into a drawing area 


Define the colors of the drawing pens (foreground pen, background pen for patterns, 
and outline pen for area-fill outlines) 


Define the pen position in the drawing area 


Draw lines, define vertex points for area-filling, and specify the area-fill color and 
pattern 


Define a pattern for patterned line drawing 


Change drawing modes 


2 Graphics Primitives 


o Read or write individual pixels in a drawing area 
o Copy rectangular blocks of drawing area data from one drawing area to another 


o Use a template (predefined shape) to draw an object into a drawing area 


COMPONENTS OF A DISPLAY 


In producing a display, you are concerned with two primary components: sprites and the 
playfield. Sprites are the easily movable parts of the display. The playfield is the static part of 
the display and forms a backdrop against which the sprites can move and with which the 
sprites can interact. 


This chapter covers the creation of the background. Sprites are described in chapter 3, 
“Animation.” 


INTRODUCTION TO RASTER DISPLAYS 


The Amiga produces its video displays on standard television or video monitors by using raster 
display techniques. The picture you see on the video display screen is made up of a series of 
horizontal video lines stacked one on top of another, as illustrated in figure 1-1. Each line 
represents one sweep of an electronic video beam, which “‘paints’’ the picture as it moves along. 
The beam sweeps from left to right, producing the full screen one line at a time. After produc- 
ing the full screen, the beam returns to the top of the display screen. 





Figure 1-1: How the Video Display Picture Is Produced 
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The diagonal lines in the figure show how the video beam returns to the start of each horizontal 
line. 


Effect of Display Overscan on the Viewing Area 


To assure that the picture entirely fills the viewable region of the screen, the manufacturer of 
the video display usually creates a deliberate overscan. That is, the video beam is swept across 
a larger section than the front face of the screen can actually display. The video beam actually 
covers 262 vertical lines. The user, however, sees only the portion of the picture that is within 
the center region of the display, which is about 200 rows, as illustrated in figure 1-2 below. The 
graphics system software lets you specify more than 200 rows. 


Overscan also restricts the amount of video data that can appear on each display line. The sys- 
tem software allows you to specify a display width of up to 352 pixels (or 704 in high-resolution 
mode) per horizontal line. Generally, however, you should use the standard values of 320 (or 640 
in high-resolution mode) for most applications. 


Overscan region. You cannot 
see it on the video screen. 


ve ieirosiansty 20 vila | 
Blanking pproximately video lines 


and 320 pixels across. 
Interval 





Figure 1-2: Display Overscan Restricts Usable Picture Area 
The time during which the video beam is in the region below the bottom line of the viewable 


area and above the top line of the next display field is called the vertzcal blanking interval. 


Color Information for the Video Lines 


The hardware reads the system display memory to obtain the color information for each line. 


As the video display beam sweeps across the screen producing the display line, it changes color, 
producing the images you have defined. 


~ 
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INTERLACED AND NON-INTERLACED MODES 


In producing the complete display (262 video lines), the video display device produces the top 
line, then the next lower line, then the next, until it reaches the bottom of the screen. When it 
reaches the bottom, it returns to the top to start a new scan of the screen. Each complete set 
of 262 lines is called a display field. It takes about 1/60th of a second to produce a complete 
display field. 


The Amiga has two vertical display modes: interlaced and non-interlaced. In non-interlaced 
mode, the video display produces the same picture for each successive display field. A non- 
interlaced display normally has about 200 lines in the viewable area (for a full-screen size 
display). 


To make the display more precise in the vertical direction, you use interlaced mode, which 
displays twice as much data in the same vertical area as non-interlaced mode. Within the same 
amount of viewable area, you can display 400 video lines instead of 200. 


For interlaced mode, the video beam scans the screen at the same rate (1/60th of a second per 
complete video display field); however, it takes two display fields to form a complete video 
display picture. During the first of each pair of display fields, the system hardware shows the 
odd-numbered lines of an interlaced display (1, 3, 5, and soon). During the second display field, 
it shows the even-numbered lines (2, 4, 6 and so on). These sets of lines are taken from data 
defining 400 lines. During the display, the hardware moves the second display field’s lines 
downward slightly from the position of the first, so that the lines in the second field are “‘inter- 
laced”’ with those of the first field, giving the higher vertical resolution of this mode. For an 
interlaced display, the data in memory defines twice as many lines as for a non-interlaced 
display, as shown in figure 1-3. 


DATA AS DATA 
DISPLAYED IN MEMORY 


Odd field — Line1 Line 1 
Even field — Line 1 Line 2 
Odd field — Line 2 Line 3 
Even field — Line 2 Line 4 


Odd field Last line Line 399 
Even field Last line Line 400 





Figure 1-3: Interlaced Mode — Display Fields and Data in Memory 
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Figure 1-4 shows a display formed as display lines 1, 2, 3, 4, ... 400. The 400-line interlaced 
display uses the same physical display area as a 200-line non-interlaced display. 


Video Display 


(400 lines) 





Figure 1-4: Interlaced Mode Doubles Vertical Resolution 


During an interlaced display, it appears that both display fields are present on the screen at the 
same time and form one complete picture. This phenomenon is called video persistence. 


HIGH- AND LOW-RESOLUTION MODES 


The Amiga also has two horizontal display modes: high-resolution and low-resolution. High- 
resolution mode provides (nominally) 640 distinct pixels (picture elements) across a horizontal 
line. Low-resolution provides (nominally) 320 pixels across each line. Low-resolution mode 


allows up to 32 colors at one time, and high-resolution mode allows 16 colors (out of 4,096 
choices) at one time. 


One other display mode affects the number of colors you can display at one time: hold-and- 
modify. Hold-and-modify mode allows you to display all 4,096 colors on the screen at once. 


FORMING AN IMAGE 


To create an image, you write data (that is, you ‘“draw”) into a memory area in the computer. 
From this memory area, the system can retrieve the image for display. You tell the system 
exactly how the memory area is organized, so that the display is correctly produced. You use a 
block of memory words at sequentially increasing addresses to represent a rectangular region of 
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data bits. Figure 1-5 shows the contents of three example memory words: 0 bits are shown as 
blank rectangles, and 1 bits as filled-in rectangles. 


Contents of three memory words, all adjacent to each other. Note that N is expressed as a byte-address. 


Mem. Location N Mem. Loc. N+2 Mem. Loc. N+4 





Figure 1-5: Sample Memory Words 
The system software lets you define linear memory as rectangular regions, called bit-planes. Fig- 


ure 1-6 shows how the system views the same three words as a bit-plane, wherein the data bits 
form an x-y plane. 


Three memory words, organized as a bit-plane. 





Figure 1-6: A Rectangular ‘“‘Look”’ at the Sample Memory Words 


Figure 1-7 shows how 4,000 words (8,000 bytes) of memory can be organized to provide enough 
bits to define a single bit-plane of a full-screen, low-resolution video display (320 x 200). 
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(TTT 


Mem. Location N Mem. Location N+38 


(TTT (TT 


Mem. Location N+40 Mem. Location N+78 


at UT 


Mem. Location N+7960 Mem. Location N+7998 





Figure 1-7: Bit-Plane for a Full-screen, Low-resolution Display 


Each memory data word contains 16 data bits. The color of each pixel on a video display line is 
directly related to the value of one or more data bits in memory, as follows: 


o If you create a display in which each pixel is related to only one data bit, you can only 
select from only two possible colors, because each bit can have a value of only 0 or 1. 


o If you use two bits per pixel, there is a choice of four different colors because there are 
four possible combinations of the values of 0 and 1 from each of the two bits. 


o If you specify three, four, or five bits per pixel, you will have eight, sixteen, or thirty- 
two possible choices of a color for each pixel. 


To create multicolored images, you must tell the system how many bits are to be used per pixel. 
The number of bits per pixel is the same as the number of bit-planes used to define the image. 


As the video beam sweeps across the screen, the system retrieves one data bit from each bit- 
plane. Each of the data bits is taken from a different bit-plane, and one or more bit-planes are 
used to fully define the video display screen. For each pixel, data-bits in the same x,y position 
in each bit-plane are combined by the system hardware to create a binary value. This value 
determines the color that appears on the video display for that pixel. (See figure 1-8.) 
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Color 
Selection 
Circuitry 


\ One of the 


Video display 
made from the 
combined bit-planes. 


pixel positions 


Bit-Planes defining a low-res display 





Figure 1-8: Bits from Each Bit-Plane Select Pixel Color 


You will find more information showing how the data bits actually select the color of the 
displayed pixel in the section called ‘“‘ViewPort Color Selection.” 


ROLE OF THE COPPER (COPROCESSOR) 


The Amiga has a special-purpose coprocessor, called the Copper, that can control nearly the 
entire graphics system. The Copper can control register updates, reposition sprites, change the 
color palette, and update the blitter. The graphics and animation routines use the Copper to 
set up lists of instructions for handling displays, and advanced users can write their own ‘‘user 
Copper lists.” 


Display Routines and Structures 


Caution: This section describes the lowest-level graphics interface to the system 
hardware. If you use any of the routines and the data structures described in these 
sections, your program will essentially take over the entire display. It will not, there- 


fore, be compatible with the multiwindow operating environment, known as Intuition, 
which is used by AmigaDOS. 
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The descriptions of the display routines, as well as those of the drawing routines, occasionally 
use the same terminology as that in Intuition: The Amiga User Interface. These routines and 
data structures are the same ones that Intuition software uses to produce its displays. 


The computer produces a display from a set of instructions you define. You organize the 
instructions as a set of parameters known as the View structure. Figure 1-9 shows how the 
system interprets the contents of a View structure. This drawing shows a complete display 
composed of two different component parts, which could, for example, be a low-resolution, mul- 
ticolored part and a high-resolution, two-colored part. 


A complete display consists of one or more ViewPorts, whose display sections are separated 
from each other by at least one blank line. The viewable area defined by each ViewPort is a 
rectangular cut from the same size (or larger) raster. You are essentially defining a display con- 


sisting of a number of vertically stacked display areas in which separate sections of graphics ras- 
ters can be shown. 


A complete display is composed of Video Display 
one (or more) ‘“ViewPorts”’ 


Background color shows here 


ViewPort #1 


ViewPorts 
must be 
separated 
by at least 
ViewPor a2 one blank line 
(may need more 
than one blank line) 





Figure 1-9: The Display Is Composed of ViewPorts 
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LIMITATIONS ON THE USE OF VIEWPORTS 


The system software for defining ViewPorts allows only vertically stacked fields to be defined. 
Figure 1-10 shows acceptable and unacceptable display configurations. If you want to create 


overlapping windows, define a single ViewPort and manage the windows yourself within that 
ViewPort. 


Incorrect 
(Does not use at least one 
blank line between 
ViewPorts) 


Acceptable 


Incorrect for ViewPorts Incorrect for ViewPorts 
(Overlapping vertical (Cannot create multiple 
windows) horizontal windows) 





Figure 1-10: Correct and Incorrect Uses of ViewPorts 


A ViewPort is related to the custom screen option of Intuition. In a custom screen, you can 
split the screen into slices as shown in the ‘“‘correct”’ illustration of figure 1-10. Each custom 
screen can have its own set of colors, use its own resolution, and show its own display area. 
Within a ViewPort — actually within its associated RastPort (drawing area definition)—it is 
possible to split the display into separate drawing areas called windows. The ViewPort is sim- 
ply an indivisible window into a possibly larger complex drawing area. 
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CHARACTERISTICS OF A VIEWPORT 


To describe a ViewPort fully, you need to set the following parameters: height, width, and 
display mode. 


In addition to these parameters, you must also tell the system the location in memory from 
which the data for the ViewPort display should be retrieved, and how to position the final 
ViewPort display on the screen. 


VIEWPORT SIZE SPECIFICATIONS 


Figure 1-11 illustrates that the variables DHeight, and DWidth specify the size of a 
ViewPort. 


Display Bit-Planes 


DHeight = how 
many lines tall 


Ee 


DWidth = how many pixels wide 





Figure 1-11: Size Definition for a ViewPort 


ViewPort Height 


The variable DHeight determines how many video lines will be reserved to show the height of 
this display segment. The size of the actual segment depends on whether you define a non- 
interlaced or an interlaced display. An interlaced display is half as tall as a non-interlaced 
display of the same number of lines. 


For example, a View consisting of two ViewPorts might be defined as follows: 


o ViewPort #1 is 150 lines, high-resolution mode (uses the top three-quarters of the 
display). 


12 Graphics Primitives 


o ViewPort #2 is 49 lines of low-resolution mode (uses the bottom quarter of the display 
and allows the space for the required blank line between ViewPorts). 


The user interface software (Intuition) assumes a standard configuration of 200 rows (400 in 
interlaced mode). 


ViewPort Width 


The DWidth variable determines how wide, in current pixels, the display segment will be. If 
you are using low-resolution mode, you should specify a width of 320 pixels per horizontal line. 
If you are using high-resolution mode, you should specify a width of 640 pixels. You may 
specify a smaller value of pixels per line to produce a narrower display segment. 


Although the system software allows you define low-resolution displays as wide as 352 pixels 
and high-resolution displays as wide as 704 pixels, you should not exceed the normal values of 
320 or 640, respectively. Because of display overscan, many video displays will not be able to 
show all of a wider display, and sprite display may be affected. If you are using hardware 
sprites or VSprites with your display, and you specify ViewPort widths exceeding 320 or 640 
pixels (for low- or high-resolution, respectively), it is likely that hardware sprites 5, 6, and 7 will 
not be rendered on the screen. These sprites may not be rendered because playfield DMA 
(direct memory access) takes precedence over sprite DMA when an extra-wide display is 
produced. 


VIEWPORT COLOR SELECTION 


The maximum number of colors that a ViewPort can display is determined by the depth of 
the BitMap that the ViewPort displays. The depth is specified when the BitMap 1s initial- 
ized. See the section below called “Preparing the BitMap Structure.” 


Depth determines the number of bit-planes used to define the colors of the rectangular image 
you are trying to build (the raster image) and the number of different colors that can be 
displayed at the same time within a ViewPort. For any single pixel, the system can display 


any one of 4,096 possible colors. 


Table 1-1 shows depth values and the corresponding number of possible colors for each value. 
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Table 1-1: Depth Values and Number of Colors in the ViewPort 


Colors Depth Value 


2 1 
4 2 
8 3 
16 4 (Note 1) 
32 5 (Notes 1,2) 
4,096 6 (Notes 1,2,3) 
32 6 (Notes 1,2) 


Notes: 
1. Single-playfield mode only —ViewPort mode not DUALPF 
2. Low-resolution mode only — ViewPort mode not HIRES 
3. Hold-and-modify mode only — ViewPort mode = HAM 


The color palette used by a ViewPort is specified in a ColorMap. See the section called 
“Preparing the ColorMap” for more information. 


Depending on whether single- or dual-playfield mode is used, the system will use different color 
register groupings for interpreting the on-screen colors. Table 1-2 below details how the depth 
and the Modes variable in the ViewPort structure affect the registers the system uses. 


Table 1-2: Single-playfield Mode (Modes variable not equal to DUALPF) 


Color 
Depth Registers Used 


01 
0-3 
0-7 
0-15 
0-31 
0-16 (if modes = HAM) 


On fh WN = 
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Table 1-3 shows the five possible combinations when the Modes variable is set to DUALPF. 


Table 1-3: Dual-playfield Mode (Modes variable = DUALPF) 


Color Color 
Depth (PF-1) Registers Depth (PF-2) Registers 


1 0,1 1 89 
2 0-3 1 8.9 
2 0-3 2 8-11 
3 0-7 2 8-11 
3 0-7 3 8-15 


The system has seven different display modes that you can specify for each ViewPort. The 
seven bits that control the modes are DUALPF, PFBA, HIRES, LACE, HAM, SPRITES, and 
VP_HIDE. A mode becomes active if you set the corresponding bit to 1 in the Modes variable 
of the ViewPort structure. After you initialize the ViewPort, you can set the bit(s) for the 
modes you want. (See the section called “Preparing the ViewPort Structure” for more informa- 
tion about initializing a ViewPort.) 


Modes DUALPF and PFBA are related. DUALPF tells the system to treat the raster specified 
by this ViewPort as the first of two independent and separately controllable playfields. It also 
modifies the manner in which the pixel colors are selected for this raster. 


When PFBA is a 1, it specifies that a second playfield has video priority over the first one. 
Playfield relative priorities can be controlled when the playfield is split into two overlapping 
regions. Single-playfield and dual-playfield modes are discussed in ‘‘Advanced Topics’’ below. 


HIRES tells the system that the raster specified by this ViewPort is to be displayed with 640 
horizontal pixels rather than 320 horizontal pixels. 


LACE tells the system that the raster specified by this ViewPort is to be displayed in inter- 
laced mode. If the ViewPort is non-interlaced and the View is interlaced, the ViewPort will 
be displayed at its specified height and will look only slightly different than it would look when 
displayed in a non-interlaced View. See “Interlaced Mode versus Non-interlaced Mode’’ below 
for more information. 


HAM tells the system to use ‘‘hold-and-modify”’ mode, a special mode that lets you display up 
to 4,096 colors on screen at the same time. It is described in the ‘“‘Advanced Topics” section. 
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SPRITES tells the system that you are using sprites in this display (either VSprites or Simple 
Sprites). This bit, when a 1, tells the software to load color registers for sprites. See chapter 3, 
“Animation,” for more information about sprites. 


VP_HIDE tells the system that this ViewPort is obscured by other ViewPorts. When a 
View is constructed, no display instructions are generated for this ViewPort. 


EXTRA_HALFBRITE is reserved for future use. 


Single-playfield Mode versus Dual-playfield Mode 


When you specify single-playfield mode (see figure 1-12), you are asking that the system treat all 
bit-planes as part of the definition of a single playfield image. Each of the bit-planes defined as 


part of this ViewPort contributes data bits that determine the color of the pixels in a single 
playfield. 


Display Screen 


Everything on the 
display is part of 
the same playfield. 


Scene (Playfield 1) 


Background color shows here 





Figure 1-12: A Single-playfield Display 


If you use dual-playfield mode (ViewPort.Modes = DUALPF), you can define two indepen- 
dent, separately controllable playfield areas (see figure 1-13). 
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Display Screen 


Two independently 
controllable displays. 


One has video priority 
over the other. 


Background color shows here 





Figure 1-13: A Dual-playfield Display 


In figure 1-13, the display mode bit PFBA is set to 1. If PFBA = 0, the relative priorities will 
be reversed; playfield 2 will appear to be behind playfield 1. 


Low-resolution Mode versus High-resolution Mode 


In low-resolution mode, horizontal lines of 320 pixels fill most of the ordinary viewing area. The 
system software lets you define a screen segment width up to 352 pixels in this mode, or you 
can define a screen segment as narrow as you desire. In high-resolution mode (also called “‘nor- 
mal” resolution), 640 pixels fill a horizontal line. In this mode you can specify any width from 0 
to 704 pixels. Overscan normally limits you to showing only O to 320 pixels per line in low- 
resolution mode or 0 to 640 pixels per line in high-resolution mode. Intuition assumes the nom1- 
nal 320-pixel or 640-pixel width (see figure 1-14). 
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320 Pixels Across 
(width of 352 is possible) 


ViewPort.Modes = 0 


640 Pixels Across 


(width of 704 is possible) ViewPort.Modes = HIRES 





Figure 1-14: How HIRES Affects Width of Pixels 


Interlaced Mode versus Non-interlaced Mode 


In interlaced mode, there are twice as many lines available as in non-interlaced mode, providing 
better vertical resolution in the same display area (see figure 1-15). 


200 lines define 


View.Modes = 0 
a full screen 


400 lines define 
a full screen 


View.Modes = LACE 





Figure 1-15: How LACE Affects Vertical Resolution 


If the View structure does not specify LACE, and the ViewPort specifies LACE, you may see 
only every other line of the ViewPort data. If the View structure specifies LACE and the 
ViewPort is non-interlaced, the same ViewPort data will be repeated in both fields. The 
height of the ViewPort display is the height specified in the ViewPort structure. If both the 
View and the ViewPort are interlaced, the ViewPort will be built with double the normal 
vertical resolution. That means it will need twice as much data space in memory as a non- 
interlaced picture for this display. 
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VIEWPORT DISPLAY MEMORY 


The picture you create in memory can be larger than the screen image that can be displayed 
within your ViewPort. This big picture (called a raster and represented by the BitMap struc- 
ture) can have a maximum size of 1,024 by 1,024 pixels. Because a picture this large cannot fit 
fully on the display, you specify which piece of it to display. Once you have selected the piece 
to be shown, you can specify where it is to appear on the screen. 


The example in figure 1-16 introduces terms that tell the system how to find the display data 
and how to display it in the ViewPort. These terms are RHeight, RWidth, RyOffset, 
Rx Offset, DHeight, DWidth, Dy Offset and DxOffset. 


(0,0) RxOffset Large picture 1024 by 800 (called a “’Raster’’) 


RyOffset 
RHeight = 800 


Display this 
part of the 
big picture 


320 


DxOffset RWidth = 1024 
(0,0) Video Display Screen 


DyOffset 
DHeight = 200 


DWidth = 320 


Background Color 





Figure 1-16: ViewPort Data Area Parameters 
The terms RHeight and RWidth do not appear in actual system data structures. They refer 


to the dimensions of the raster and are used here to relate the size of the raster to the size of 
the display area. RHeight is the number of rows in the raster, and RWidth is the number of 
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bytes per row times 8. The raster shown in the figure is too big to fit entirely in the display 
area, so you tell the system which pixel of the raster should appear in the upper left corner of 
the display segment specified by your ViewPort. The variables that control that placement 
are Ry Offset and Rx Offset. 


To compute RyOffset and RxOffset, you need RHeight, RWidth, DHeight, and DWidth. 
The DHeight and DWidth variables define the height and width in pixels of the portion of the 
display that you want to appear in the ViewPort. The example shows a full-screen, low- 
resolution mode (320-pixel), non-interlaced (200-line) display formed from the larger overall 
picture. 


Normal values for RyOffset and RxOffset are defined by the formulas: 


0 < = RyOffset < = (RHeight - DHeight) 
0 < = RxOffset < = (RWidth - DWidth) 


Once you have defined the size of the raster and the section of that raster that you wish to 
display, you need only specify where to put this ViewPort on the screen. This is controlled by 
the variables DyOffset and DxOffset. A value of 0 for each of these offsets places a normal- 
sized picture in a centered position at the top, bottom, left and right on the display screen. 
Possible values for DyOffset range from -16 to +200 (-32 to +400 if View.Modes includes 
LACE). Possible values for DxOffset range from -16 to +352 (-32 to +704 if 
ViewPort.Modes includes HIRES). 


The parameters shown in the figure above are distributed in the following data structures: 


o RasInfo (information about the raster) contains the variables RxOffset and Ry Offset. 
It also contains a pointer to the BitMap structure. 


o View (information about the whole display) includes the variables that you use to posi- 
tion the whole display on the screen. The View structure contains a Modes variable 
used to determine if the whole display is to be interlaced or non-interlaced. It also con- 
tains pointers to its list of WiewPorts and pointers to the Copper instructions pro- 
duced by the system to create the display you have defined. 


o ViewPort (information about this piece of the display) includes the values DxOffset 
and DyOffset that are used to position this slice relative to the overall View. The 
ViewPort also contains the variables DHeight and DWidth, which define the size of 
this slice; a Modes variable; and a pointer to the local ColorMap. Each ViewPort 
also contains a pointer to the next ViewPort. You create a linked list of ViewPorts 
to define the complete display. 


o BitMap (information about memory usage) tells the system where to find the display 
and drawing area memory and shows how this memory space is organized. 
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You must allocate enough memory for the display you define. The memory you use for the 
display may be shared with the area control structures used for drawing. This allows you to 
draw into the same areas that you are currently displaying on the screen. 


As an alternative, you can define two BitMaps. One of them can be the active structure (that 
being displayed) and the other can be the inactive structure. If you draw into one BitMap 
while displaying another, the user cannot see the drawing taking place. This is called double- 
buffering of the display. See ‘“‘Advanced Topics” below for an explanation of the steps required 
for double-buffering. Double-buffering takes twice as much memory as single-buffering because 
two full displays are produced. 


To determine the amount of required memory for each ViewPort for single-buffering, you can 
use the following formula. 


bytes_per_ViewPort = Depth * RASSIZE (Width, Height); 


RASSIZE is a system macro attuned to the current design of the system memory allocation for 
display rasters. See graphics/gfxmacros.h for the formula with which RASSIZE is calculated. 


For example, a 32-color ViewPort (depth = 5), 320 pixels wide by 200 lines high uses 40,000 
bytes (as of this writing). A 16-color ViewPort (depth = 4), 640 pixels wide by 400 lines high 
uses 128,000 bytes (as of this writing). 


FORMING A BASIC DISPLAY 


This section offers an example that shows how to create a single ViewPort with a size of 200 
lines, in which the area displayed is the same size as the big picture (raster) stored in memory. 
The example also shows how this ViewPort becomes the single display segment of a View 
structure. Following the description of the individual operations, the ‘‘“Graphics Example Pro- 
gram’’ section pulls all of the pieces into a complete executable program. Instead of linking 
these routines to drawing routines, the example allocates memory specifically and only for the 
display (instead of sharing the memory with the drawing routines) and writes data directly to 
this memory. This keeps the display and the drawing routines separate for purposes of 
discussion. 


Here are the data structures that you need to define to create a basic display: 


struct View v; /* The name used here for a View is v, 
struct ViewPort vp; * for a ViewPort is vp, 

struct BitMap b; * for a BitMap is b, 

struct RasInfo ri; * and for a RasInfo is ri. */ 
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Opening the Graphics Library 


Most of the system routines used here are located in the graphics library. When you compile 
your program, you must provide a way to tell the compiler to link your calling sequences into 
the routine library in which they are located. You accomplish this by declaring the variable 
called GfxBase. Then, by opening the graphics library, you provide the value (address of the 
library) that the system needs for linking with your program. See the “Libraries” chapter in 
the Amiga ROM Kernel Reference Manual: Exec for more information. 


Here is a typical sequence: 


struct GfxBase *GfxBase; /* declare the name *GfxBase as a 
* pointer to the corresponding library */ 


Preparing the View Structure 
The following code section prepares the View structure for further use: 


Init View( &v ); /* initialize the View structure */ 
v.ViewPort = &vp;/* tell the View structure where to find the 
* first ViewPort in a possible list of Viewports * / 


Preparing the ViewPort Structure 
The following code section prepares the ViewPort structure for further use: 


InitVPort( &vp ); /* initialize the structure (set up default values) */ 
vp.DWidth = WIDTH; /* how wide is the display */ 
vp.DHeight = HEIGHT; /* how tall is the display for this ViewPort */ 
vp.RasInfo = &ri; /* pointer to a RasInfo structure */ 
vp.ColorMap = GetColorMap(32); /* using a 32-color map */ 
The InitVPort() routine presets certain default values. The defaults include: 
o Modes variable set to zero—this means you select a low-resolution display. 
o Next variable set to zero—no other ViewPort is linked to this one. If you want to 


have multiple ViewPorts in a single View, you must create the link yourself. The last 
ViewPort in the chain must have a Next value of 0. 
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If you have defined two ViewPorts, such as 


struct ViewPort vpA; 
struct ViewPort vpB; 


and you want them to both be part of the same display, you must create a link between them, 
and a NULL link at the end of the chain of ViewPorts: 


vpA.Next = &vpB; _ _=s/* tell first one the address of the second */ 
vpB.Next = NULL;  /* after this one, there are no others */ 


Preparing the BitMap Structure 


The BitMap structure tells the system where to find the display and drawing memory and how 
this memory space is organized. The following code section prepares a BitMap structure, 
including allocation of memory for the bit-map. For this example, this memory is used only for 
the display and is not shared with any drawing routines. The example writes directly to the 
display area. 


/* initialize the BitMap structure */ 
InitBitMap( &b, DEPTH, WIDTH, HEIGHT ); 
/* now allocate some memory that can be 
* be linked into the BitMap for display purposes * / 
for( i=0; i<DEPTH, i++) 
{ 
b.Planes[i] = (PLANEPTR)AllocRaster(WIDTH, HEIGHT); 


This code allocates enough memory to handle the display area for as many bit-planes as the 
depth you have defined. This code segment does not include the error-checking that is present 
in the full example later on. 


Preparing the RasInfo Structure 


The RasInfo structure provides information to the system about the location of the BitMap as 
well as the positioning of the display area as a window against a larger drawing area. Use the 
following steps to prepare the RasInfo structure: 
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ri.BitMap = &b;_ /* specify address of the BitMap structure */ 
ri.Rx Offset = 0; 
ri.RyOffset = 0; /* match the upper lefthand corner of the 
* display area with the upper left corner of 
* the drawing area - see figure 1-16 */ 
rinext = NULL; /* fora single playfield display, there 
* is only one RasInfo structure present * / 


Preparing the ColorMap Structure 


Interrupts should be used to display this ViewPort. When the View is created, Copper 
instructions are generated to change the current contents of each color register just before the 
topmost line of a ViewPort so that this ViewPort’s color registers will be used for interpret- 
ing its display. 


Here are the steps normally used for initializing a ColorMap: 


/* define some colors in an array of words */ 
UWORD colortable [] = { 0, Oxf00, OxOf0, OxOOf } 

/* allocate space and get a pointer to it */ 

/* 4 colors in this table (4 registers for Copper 

* to reload before this ViewPort is displayed */ 
vp.ColorMap = GetColorMap (4); 
LoadRGBA4( vp, ColorTable, 4 ) 


Note: The ‘‘4” in the name LoadRGBA() refers to the fact that each of the red, green, and 
blue values in a color table entry consists of four bits. It has nothing to do with the fact that 


this particular color table contains four entries, which is a result of the choice of DEPTH = 2 
for this example. 


From the section called ““ViewPort Color Selection,” notice that you might need to specify more 
colors in the color map than you think. If you use a dual-playfield display (covered later in this 
chapter) with a depth of 1 for each of the two playfields, this means a total of four colors (two 
for each playfield). However, because playfield 2 uses color registers starting from number 8 on 
up when in dual-playfield mode, the color map must be initialized to contain at least 10 entries. 
That is, it must contain entries for colors 0 and 1 (for playfield 1) and color numbers 8 and 9 
(for playfield 2). Space for sprite colors must be allocated as well. 
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Creating the Display Instructions 


Now that you have initialized the system data structures, you can request that the system 
prepare a set of display instructions for the Copper using these structures as input data. Dur- 
ing the one or more blank vertical lines that precede each ViewPort, the Copper is busy chang- 
ing the characteristics of the display hardware to match the characteristics you expect for this 
ViewPort. This may include a change in display resolution, a change in the colors to be used, 
or other user-defined modifications to system registers. 


Here is the code that creates the display instructions: 


MakeVPort( &v, &vp ); 


In this line of code, &v is the address of the View structure and &vp is the address of the first 
ViewPort structure. Using these structures, the system has enough information to build the 
instruction stream that defines your display. 


MakeVPort() creates a special set of instructions that controls the appearance of the display. 
If you are using animation, the graphics animation routines create a special set of instructions to 
control the hardware sprites and the system color registers. In addition, the advanced user can 


create special instructions (called user Copper instructions) to change system operations based 
on the position of the video beam on the screen. 


All of these special instructions must be merged together before the system can use them to pro- 
duce the display you have designed. This is done by the system routine MrgCop() (which 
stands for ‘‘“Merge Coprocessor Instructions’’). Here is a typical call: 


MrgCop (&v); /* merge this View’s Copper instructions 
* into a single instruction list */ 


LOADING AND DISPLAYING THE VIEW 


To display the View, you need to load it using LoadView() and turn on the direct memory 
access (DMA). A typical call is shown below. 


LoadView( &v ); 
where &v is the address of the View structure defined in the example above. 
Two macros control display DMA: ON_DISPLAY and OFF_DISPLAY. They simply turn 


the display DMA control bit in the DMA control register on or off. After you have loaded a 
new View, you use ON_DISPLAY to allow the system DMA to display it on the screen. 
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If you are drawing to the display area and do not want the user to see intermediate steps in the 
drawing, you can turn off the display. Because OF F_DISPLAY shuts down the display DMA 
and possibly speeds up other system operations, it can be used to provide additional memory 
cycles to the blitter or the 68000. The distribution of system DMA, however, allows four- 
channel sound, disk read/write, and a sixteen-color, low-resolution display (or four-color, high- 
resolution display) to operate at the same time with no slowdown (7.1 megahertz effective rate) 
in the operation of the 68000. 


GRAPHICS EXAMPLE PROGRAM 


The program below creates and displays a single-playfield display that is 320 pixels wide, 200 
lines high, and two bit-planes deep. 


#include ”exec/types.h” 
#include ” graphics/gfx.h” 
#include ”hardware/dmabits.h” 
#include ”hardware/custom.h” 
#include ”hardware/blit.h” 
#include ” graphics/gfxmacros.h” 
#include ” graphics /copper.h” 
#include ” graphics/view.h” 
#include ” graphics/gels.h” 
#include ” graphics /regions.h” 
#include ” graphics/clip.h” 
#include ” exec/exec.h” 
#include ” graphics/text.h” 
#include ” graphics/gfxbase.h” 


#define DEPTH 2 - - 

#define WIDTH 320 

#define HEIGHT 200 

#-define NOT_ENOUGH_MEMORY -1000 


/* construct a simple display */ 


struct View v; 

struct ViewPort vp; 

struct ColorMap *cm; /* pointer to ColorMap structure, dynamic alloc */ 
struct RasInfo ri; 

struct BitMap b; 

struct RastPort rp; 


LONG 1}; 
SHORT j,k,n; 
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extern struct ColorMap *GetColorMap(); 
struct GfxBase *GfxBase; 


struct View *oldview; /* save pointer to old View so can restore */ 


/* black, red, green, blue */ 


USHORT colortable|] = { 0x000, Oxf00, Ox0f0, OxO0f }; /* my own colors */ 
SHORT boxoffsets|] = { 802, 2010, 3218 }; /* where to draw boxes */ 


UBYTE *displaymem; 
UWORD ¥«colorpalette; 


main() 


{ 


GfxBase = (struct GfxBase *)OpenLibrary(” graphics.library” ,O); 

if (GfxBase == NULL) exit(1); 

oldview = GfxBase->ActiView; /* save current View to restore later */ 
/* example steals screen from Intuition if Intuition is around */ 


Init View(&v); /* initialize View */ 
InitVPort(&vp); /* init ViewPort */ 
v.ViewPort = &vp;_ _/* link View into ViewPort */ 


/* init bit map (for RasInfo and RastPort) */ 
InitBitMap(&b, DEPTH, WIDTH, HEIGHT); 


/* (init RasInfo) */ 
n.BitMap = &b; 
ri.RxOffset — 0; 
ri.RyOffset = 0; 
ri.Next = NULL; 


/* now specify critical characteristics */ 
vp.DWidth = WIDTH; 

vp.DHeight = HEIGHT; 

vp.RasInfo = &ri; 


/* (init color table) */ 
cm = GetColorMap(4); /* 4 entries, since only 2 planes deep */ 
colorpalette = (UWORD *)cm->ColorTable; 
for(i=0; i<4; i++) { 
*colorpalette++ = colortable|i|; 
} 


/* copy my colors into this data structure */ 
vp.ColorMap = cm; /* link it with the ViewPort */ 
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j 


/* allocate space for bitmap */ 


for(i=0; i< DEPTH; i++) 


b.Planes|i] = (PLANEPTR)AllocRaster(WIDTH,HEIGHT); 
if(b.Planes|i] === NULL) exit(NOT_ENOUGH_MEMORY); 
j 


MakeVPort( &v, &vp ); /* construct Copper instruction (prelim) list */ 
MrgCop( &v ); /* merge preliminary lists together into a real 
* Copper list in the view structure. */ 


for(i=0; 1<2; 1++) 

{ 
displaymem = (UBYTE *)b.Planes|i]; 
BltClear(displaymem,RASSIZE(WIDTH,HEIGHT),0) 


} 


Load View( &v); 
/* now fill some boxes so that user can see something */ 
/* always draw into both planes to assure true colors */ 
for(n=1; n<4; n++) /* three boxes */ 
{ 
for(k=0; k<2; k++) 
{ 
/* boxes will be in red, green and blue */ 
displaymem = b.Planes|k] + boxoffsets[n- 1]; 
DrawF illedBox(n,k); 


} 


Delay(50*10); /* wait for 10 seconds */ 

Load View(oldview); /* put back the old View */ 
FreeMemory(); /* exit gracefully */ 
CloseLibrary(GfxBase); /* since program opened library, close it */ 


/* end of main() */ 


/* return user- and system-allocated memory to sys manager */ 
FreeMemory() 


{ 


/* free drawing area */ 


for(i=0; i<DEPTH; i++) 
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{ 
} 


/* free the color map created by GetColorMap() */ 
FreeColorMap(cm); 

/* free dynamically created structures */ 
FreeVPortCopLists(&vp); 
FreeCprList(v.LOFCprList); 

return(0); 


FreeRaster(b.Planes|i], WIDTH,HEIGHT); 


j 
DrawF illed Box(fillcolor,plane) 


SHORT fillcolor,plane; 


{ 
UBYTE value; 


for(j=0; }<100; j++) 
{ 


if((fillcolor & (1 << plane)) != 0) 
‘ 


value = Oxff; 


value = 0; 


} 
for(i=0; i< 20; i++) 


{ 
} 


displaymem += (b.BytesPerRow - 20); 


*displaymem++ = value; 


} 


return(0); 


Exiting Gracefully 


The sample program above provides a way of exiting gracefully, returning to the memory 
manager all dynamically-allocated memory chunks. Notice the calls to FreeRaster() and 
FreeColorMap(). These calls correspond directly to the allocation calls AllocRaster() and 
GetColorMap() located in the body of the program. Now look at the calls within 
FreeMemory() to FreeVPortCopLists() and FreeCprList(). When you call MakeVPort(), 
the graphics system dynamically allocates some space to hold intermediate instructions from 
which a final Copper instruction list is created. When you call MrgCop(), these intermediate 
Copper lists are merged together into the final Copper list, which is then given to the hardware 
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for interpretation. It is this list that provides the stable display on the screen, split into 
separate ViewPorts with their own colors and resolutions and so on. 


When your program completes, you must see that it returns all of the memory resources that it 
used so that those memory areas are again available to the system for reassignment to other 
projects. Therefore, if you use the routines MakeVPort() or MrgCop(), you must also 
arrange to use FreeCprList() (pointing to each of those lists in the View structure) and 
FreeVPortCopLists() (pointing to the ViewPort that is about to be deallocated). If your 
view is interlaced, you will also have to call FreeCprList(&v.SHFCprList) because an inter- 
laced view has a separate Copper list for each of the two fields displayed. 


As a final caveat, notice that when you do free everything, the memory manager or other pro- 
grams may immediately change the contents of the freed memory. Therefore, if the Copper is 
still executing an instruction stream (as a result of a previous LoadView() ) when you free that 
memory, the display will go “‘south.’”’ You will probably want to turn off the display or provide 
an alternate Copper list when this one is to be deallocated. 


Advanced Topics 


CREATING A DUAL-PLAYFIELD DISPLAY 


In dual-playfield mode, you have two separately controllable playfields. In this mode, you 
always define two RasInfo data structures. Each of these structures defines one of the 
playfields. There are seven different ways you can configure a dual-playfield display, because 
there are five different distributions of the bit-planes which the system hardware allows. Table 
1-4 shows these distributions. 
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Table 1-4: Bit-Plane Assignment in Dual-playfield Mode 


Number of Playfield 1 Playfield 2 
Bit-planes Depth Depth 


moh WD KK CO 
WWN NHN = — CO 
WHO NW KF —- CO SO 


Recall that if you set PFBA in the ViewPort Modes variable to 1, you can swap playfield 
priority and display playfield 2 in front of playfield 1. In this way, you can get more bit-planes 
in the background playfield than you have in the foreground playfield. If you create a display 
with multiple ViewPorts, only for this ViewPort will the playfield priority be changed. 


Playfield 1 is defined by the first of the two RasInfo structures. Playfield 2 is defined by the 
second of the two RasInfo structures. 


When you call MakeVPort(), you use parameters as follows: 


MakeVPort( &view, &viewport ); 


The ViewPort Modes variable must include the DUALPF bit. This tells the graphics system 
that there are two RasInfo structures to be used. 


In summary, to create a dual-playfield display you must do the following things: 
o Allocate one View structure 
o §6Allocate two BitMap structures 
o Allocate two RasInfo structures (linked together), each pointing to different BitMaps 
o Allocate one ViewPort structure 


o Set up a pointer in the ViewPort structure to the playfield 1 RasInfo 
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o Initialize each BitMap structure to describe one playfield, using one of the permissible 
bit-plane distributions shown in table 1-4 and allocate memory for the bit-planes them- 
selves. Note that BitMap 1 and BitMap 2 need not be the same width and height. 

o Initialize the ViewPort structure 

o Set the DUALPF (and possibly the PFBA) bit in the ViewPort Modes variable 

o Call MakeVPort() 

o Call MrgCop() 


For display purposes, each of the two BitMaps is assigned to a separate playfield display. 


To draw separately into the BitMaps, you must also assign these BitMaps to two separate 
RastPorts. The section called ‘Initializing the RastPort’’ shows you how to use a RastPort 
data structure to control your drawing routines. 


CREATING A DOUBLE-BUFFERED DISPLAY 


To produce smooth animation or other such effects, it is occasionally necessary to double-buffer 
your display. To prevent the user from seeing your graphics rendering while it is in progress, 
you will want to draw into one memory area while actually displaying a different area. 


Double-buffering consists of creating two separate display areas and two sets of pointers to those 
areas for a single View. 


To create a double-buffered display, you must perform these actions: 
o 6©Allocate two BitMap structures 
o §6©Allocate one RasInfo structure 
o Allocate one ViewPort structure 
o §6©Allocate one View structure 


o Initialize each BitMap structure to describe one drawing area and allocate memory for 
the bit-planes themselves 


o Create a pointer for each BitMap 
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o Create a pointer for the View long-frame Copper list (LOFCprList) and short-frame 
Copper list (SHFCprList) for each of two alternate display fields. The SHFCprList 
is for interlaced displays. 


o Initialize the RasInfo structure, setting the BitMap pointer to point to one of the two 
BitMaps you have created 


o Call MakeVPort() 
o Call MrgCop() 


o Call LoadView() 


When you call MrgCop(), the system uses all of the information you have provided in the vari- 
ous data structures to create a list of instructions for the Copper to execute. This list tells the 
Copper how to split the display and how to specify colors for the various portions of the 
display. When the steps shown above have been completed, the system will have allocated 
memory for a long-frame (LOF) Copper list and a short-frame (SHF) Copper list and will have 
set pointers called LOFCprList and SOFCprList in the View structure. The long-frame 
Copper list is normally used for all non-interlaced displays, and the short-frame Copper list is 


used only when interlaced mode is turned on. The pointers point to the two sets of Copper 
instructions. 


The LOFCprList and SHFCprList pointers are initialized when MrgCop() is called. The 
instruction stream referenced by these pointers includes references to the first BitMap. 


You must now do the following: 


o Save the current values in back-up pointers and set the values of LOFCprList and 
SHFCprlist in the View structure to zero. When you next perform MrgCop(), the 
system automatically allocates another memory area to hold a new list of instructions 
for the Copper. 


o Install the pointer to the other BitMap structure in the RasInfo structure before your 
call to MakeVPort(), and then call MakeVPort and MrgCop. 


Now you have created two sets of instruction streams for the Copper, one of which you have 
saved in a pair of pointer variables. The other has been newly created and is in the View 
structure. You can save this new set of pointers as well, swapping in the set that you want to 
use for display, while drawing into the BitMap that is not on the display. Remember that you 
will have to call FreeCprList() on both sets of Copper lists when you have finished. 
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HOLD-AND-MODIFY MODE 


In hold-and-modify mode you can create a single-playfield display in which 4,096 different colors 
can be displayed simultaneously. This requires that your ViewPort be defined using six bit- 
planes and that you set the HAM bit in the ViewPort Modes variable. 


When you draw into the BitMap associated with this ViewPort, you can choose one of four 
different ways of drawing into the BitMap. (Drawing into a BitMap is shown in the next sec- 
tion, ‘Drawing Routines.”’) If you draw using color numbers 0-15, the pixel you draw will 
appear in the color specified in that particular system color register. If you draw with any other 
color value from 16-31, the color displayed depends on the color of the pixel that is to the 
immediate left of this pixel on the screen. For example, hold constant the contents of the red 
and the green parts of the previously produced color, and take the rest of the bits of this new 
pixel’s color register number as the new contents for the blue part of the color. Hold-and- 
modify means hold part and modify part of the preceding defined pixel’s color. 


Note that a particular hold-and-modify pixel can only change one of the three color values at a 
time. Thus, the effect has a limited control. 


In hold-and-modify mode, you use all six bit-planes. Planes 5 and 6 are used to modify the way 
bits from planes 1 - 4 are treated, as follows: 


o If the 6-5 bit combination from planes 6 and 5 for any given pixel is 00, normal color 
selection procedure is followed. Thus, the bit combinations from planes 4 - 1, in that 
order of significance, are used to choose one of 16 color registers (registers 0-15). 


If only five bit-planes are used, the data from the sixth plane is automatically supplied 
with the value as 0. 


o If the 6-5 bit combination is 01, the color of the pixel immediately to the left of this 
pixel is duplicated and then modified. The bit combinations from planes 4 - 1 are used 


to replace the four “blue”’ bits in the pixel color without changing the value in any color 
register. 


o If the 6-5 bit combination is 10, the color of the pixel immediately to the left of this 
pixel is duplicated and then modified. The bit combinations from planes 4 - 1 are used 
to replace the four “red” bits. 


o If the 6-5 bit combination is 11, the color of the pixel immediately to the left of this 
pixel is duplicated and then modified. The bit combinations from planes 4 - 1 are used 


to replace the four “‘green”’ bits. 


o At the leftmost edge of each line, hold-and-modify begins with the background color. 
The color choice does not carry over from the preceding line. 
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Drawing Routines 


Most of the graphics drawing routines require information about how the drawing is to take 
place. For this reason, the graphics support routines provide a data structure called a 
RastPort, which contains information essential to the graphics drawing functions. In using 
most of the drawing functions, you must pass them a pointer to your RastPort structure. As- 
sociated with the RastPort is another data structure called a BitMap, which contains a 
description of the organization of the data in the drawing area. 


INITIALIZING A BITMAP STRUCTURE 


The RastPort contains information for controlling the drawing. In order to use the graphics, 
you also need to tell the system the memory area location where the drawing will occur. You 
do this by initializing a BitMap structure, defining the characteristics of the drawing area, as 
shown in the following example. This was already shown in the section called ‘‘Forming a Basic 
Display,” but it is repeated here because it relates to drawing as well as to display routines. 
You need not necessarily use the same BitMap for both the drawing and the display. 


struct BitMap myBitMap; 
SHORT depth = 3;/* max of eight colors ... going to need three 
* bit-planes to represent this number of colors */ 


SHORT width = 320; 
SHORT height — 200; 


ee 


InitBitMap( &myBitMap, depth, width, height); 


INITIALIZING A RASTPORT STRUCTURE 


Before you can use a RastPort for drawing, you must initialize it. Here is a sample initializa- 
tion sequence: 


struct RastPort myRastPort; 
InitRastPort(&myRastPort); 


/* now link together the BitMap and the RastPort */ 
myRastPort.BitMap = &myBitMap; 


Note that you cannot perform the link until after the RastPort has been initialized. 
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The RastPort data structure can be found in the include files rastport.h and rastport.z. It con- 
tains the following information: 


o Drawing pens 

o Drawing modes 

o Patterns 

o Text attributes and font information 

o  Area-filling information 

o Graphics elements information for animation 
o Current pen position 

o A write mask 

Oo Some graphics private data 

o A pointer for user extensions 


The following sections explain each of the items in the RastPort structure. 


Drawing Pens 


The Amiga has three different drawing “pens’’ associated with the graphics drawing routines. 
These are: 


o FgPen—the foreground or primary drawing pen. For historical reasons, it 1s also 


called the A-Pen. 


o BgPen—the background or secondary drawing pen. For historical reasons, it is also 


called the B-Pen. 


o AOIlPen—the area outline pen. For historical reasons, it is also called the O-Pen. 


A drawing pen variable in the RastPort contains the current value (range 0-255) for a particu- 
lar color choice. This value represents a color register number whose contents are to be used in 
rendering a particular type of image. In essence, the bits of a “‘pen’’ determine which bit-planes 
are affected when a color is written into a pixel (as determined by the drawing mode and 
modified by the pattern variables and the write mask as described below). The drawing rou- 
tines support BitMaps up to eight planes deep, allowing for future expansion in the hardware. 
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Note: The Amiga 1000 contains only 32 color registers. Any range beyond that repeats the 
colors in 0-31. For example, pen numbers 32-63 refer to the colors in registers 0-31. 


The color in FgPen is used as the primary drawing color for rendering lines and areas. This 
pen is used when the drawing mode is JAMI (see the next section for drawing modes). JAMI1 
specifies that only one color is to be “jammed” into the drawing area. 


You establish the color for FgPen using the statement: 


SetAPen( &myRastPort, newcolor ); 


The color in BgPen is used as the secondary drawing color for rendering lines and areas. If you 
specify that the drawing mode is JAM2 (jamming two colors) and a pattern is being drawn, the 
primary drawing color (FgPen) is used where there are 1s in the pattern. The secondary draw- 
ing color (BgPen) is used where there are Os in the pattern. 


You establish the drawing color for BgPen using the statement: 


SetBPen( &myRastPort, newcolor ); 


The area outline pen AOI]Pen is used in two applications: area fill and flood fill. (See ‘‘Area 
Fill Operations”’ below.) In area fill, you can specify that an area, once filled, can be outlined in 
this AOIPen color. In flood fill (in one of its operating modes) you can fill until the flood-filler 
hits a pixel of the color specified in this pen variable. 


You establish the drawing color for AO|]Pen using the statement: 


SetOPen( &myRastPort, newcolor ); 


Drawing Modes 


Four drawing modes may be specified: 


JAMI Whenever you execute a graphics drawing command, one color is jammed into 
the target drawing area. You use only the primary drawing pen color, and for 
each pixel drawn, you replace the color at that location with the FgPen color. 


JAM2 Whenever you execute a graphics drawing command, two colors are jammed into 
the target drawing area. This mode tells the system that the pattern variables 
(both line pattern and area pattern —see the next section) are to be used for the 
drawing. Wherever there is a 1 bit in the pattern variable, the FgPen color re- 
places the color of the pixel at the drawing position. Wherever there is a O bit in 
the pattern variable, the BgPen color is used. 
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COMPLEMENT 
For each 1 bit in the the pattern, the corresponding bit in the target area is 
complemented —that is, its state is reversed. As with all other drawing modes, 
the write mask can be used to protect specific bit-planes from being modified. 
Complement mode is often used for drawing and then erasing lines. 


INVERSEVID 
This is the drawing mode used primarily for text. If the drawing mode is 
(JAMI1 | INVERSEVID), the text appears as a transparent letter surrounded by 
the FgPen color. If the drawing mode is (JAM2|INVERSEVID ), the text ap- 
pears as in (JAM1|INVERSEVID ) except that the BgPen color is used to draw 


the text character itself. In this mode, the roles of FgPen and BgPen are 
effectively reversed. 


You set the drawing modes using the statement: 


SetDrMd( &myRastPort, newmode ); 


Patterns 


The RastPort data structure provides two different pattern variables that it uses during the 
various drawing functions: a line pattern and an area pattern. The line pattern is 16 bits wide 
and is applied to all lines. When you initialize a RastPort, this line pattern value is set to all 
ls (hex FFFF), so that solid lines are drawn. You can also set this pattern to other values to 


draw dotted lines if you wish. For example, you can establish a dotted line pattern with the 
statement: 


SetDrPt( &myRastPort, Oxcccc ); 


where “‘cccc”’ is a bit-pattern, 1100110011001100, to be applied to all lines drawn. If you draw 
multiple, connected lines, the pattern cleanly connects all the points. 


The area pattern is 16 bits wide and its height is some power of two. This means that you can 


define patterns in heights of 1, 2, 4, 8, 16, and so on. To tell the system how large a pattern 
you are providing, include this statement: 


SetAfPt( &myRastPort, &myAreaPattern, power_of_two ); 


where &myAreaPattern is the address of the first word of the area pattern and 
power_of_two specifies how many words are in the pattern. For example: 
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USHORT myAreaPattern[ ] = { 
Ox ff00, 
Ox ff00, 
Ox OOff, 
Ox O0O0ff, 
OxfOfo, 
OxfOfo, 
Ox OfOf, 
Ox O0fOf 


}3 


SetAfPt( &myRastPort, &myAreaPattern, 3 ); 


This example produces a pattern that is a large checkerboard above a small checkerboard. 
Because power_of_two is set to 3, the pattern is 2 to the 3rd, or 8, rows high. 


Pattern Positioning 


The pattern is always positioned with respect to the upper left corner of the RastPort drawing 


area (the 0,0 coordinate). If you draw two rectangles whose edges are adjacent, the pattern will 
be continuous across the rectangle boundaries. 


Multicolored Patterns 


The last example above produces a two-color pattern with one color where there are 1s and the 
other color where there are Os in the pattern. A special mode allows you to develop a pattern 


having up to 256 colors. To create this effect, specify power_of_two as a negative value 
instead of a positive value. 


The following initialization establishes an 8-color checkerboard pattern where each square in the 
checkerboard has a different color. The checkerboard is 2 squares wide by 4 squares high. 


USHORT myAreaPattern(3](8] = { 
{ 

0x0000, /* plane O pattern */ 
0x0000, 

Ox fiff, 

Ox fiff, 

0x0000, 

0x0000, 

Ox fiff, 

Ox fiff, 


bs 
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0x0000, /* plane 1 pattern */ 
0x0000, 

0x0000, 

0x0000, 

Ox fff, 

Ox fff, 

Ox fiff, 

Ox fiff, 


Ox ff00, /* plane 2 pattern */ 
Ox ff00, 
Oxff00, 
Oxff00, 
Ox ff00o, 
Ox ffoo, 
Ox ff0O, 
Ox ff00 


}3 
SetAfPt( &myRastPort, &myAreaPattern, -3 ); 


/* when doing this, it is best to set three other parameters as follows: */ 
SetAPen( &myRastPort, 255); 

SetBPen( &myRastPort, 0); 

SetDrMd( &myRastPort, JAM2); 


If you use this multicolored pattern mode, you must provide as many planes of pattern data as 
there are planes in your BitMap. 


Text Attributes 


Text attributes and font information are set by calls to the font routines. These are covered 
separately in chapter 4, “Text.” 
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Area-fill Information 


Two structures in the RastPort—AreaInfo and TmpRas— define certain information for 
area filling operations. The AreaInfo pointer is initialized by a call to the routine InitArea(). 


InitArea (&myRastPort, &areabuffer, count); 


To use area fill, you must first provide a work space in memory for the system to store the list 
of points that define your area. You must allow a storage space of 5 bytes per vertex. To 
create the areas in the work space, you use the functions AreaMove(), AreaDraw/(), and 


AreaEnd(). 


Typically, you prepare the RastPort for area-filling using a sequence like the following: 


UWORD areabuffer [250]; 


/* allow up to 100 vertices in the definition of an area * / 
InitArea (&myRastPort, &areabuffer(0], 100); 


The area buffer must start on a word boundary. That is why the sample declaration shows 
areabuffer as composed of unsigned words (250), rather than unsigned bytes (500). It still 
reserves the same amount of space, but aligns the data space correctly. 


In addition to the AreaInfo structure in the RastPort, you must also provide the system with 
some work space to build the object whose vertices you are going to define. This requires that 
you initialize a TmpRas structure, then point to that structure for your RastPort to use. 


Here is sample code that builds and initializes a TmpRas. Note that the area to which 
TmpRas.RasPtr points must be at least as large as the area (width times height) of the larg- 
est rectangular region you plan to fill. Typically, you allocate a space as large as a single bit- 


plane (usually 320 by 200 bits for low-resolution mode, 640 by 200 bits for high-resolution 
mode). 


PLANEPTR myplane; 
myplane = AllocRaster(320,200); /* get some space */ 
if (myplane == 0) exit(1); /* stop if no space */ 
myRastPort. TmpRas= InitTmpRas(&myTmpRas, 

my plane,RASSIZE(320,200)); 


When you use functions that dynamically allocate memory from the system, you must 
remember to return these memory blocks to the system before your program exits. See the 
description of FreeRaster() in the ‘Library Summaries” appendix. 
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Graphics Element Pointer 


The graphics element pointer in the RastPort structure is called GelsInfo. If you are doing 
graphics animation using the GELS system, this pointer must refer to a properly initialized 
GelsInfo structure. See chapter 3, ‘Animation,’ for more information. 


Current Pen Position 


The graphics drawing routines keep the current position of the drawing pen in the variables 
cp_x and cp_y, for the horizontal and vertical positions, respectively. The coordinate location 
0,0 is in the upper left corner of the drawing area. The x value increases proceeding to the 
right; the y value increases proceeding toward the bottom of the drawing area. 


Write Mask 


The write mask is a RastPort variable that determines which of the bit-planes are currently 
writable. For most applications, this variable contains all 1s (hex ff). This means that all bit- 
planes defined in the BitMap are affected by a graphics writing operation. You can selectively 


disable one or more bit-planes by simply specifying a O bit in that specific position in the control 
byte. For example: 


myRastPort.Mask = OxFB; /* disable bit-plane 2 */ 


USING THE GRAPHICS DRAWING ROUTINES 


This section shows you how to use the Amiga drawing routines. All of these routines work 
either on their own or with the windowing system and layer library. See chapter 2, ‘‘Layers,”’ 
or Intuition: The Amiga User Interface for details about using the layer library and windows. 


As you read this section, keep in mind that to use the drawing routines, you need to pass them 
a pointer to a RastPort. You can define the RastPort directly, as shown in the sample pro- 


gram segments in preceding sections, or you can get a RastPort from your Window structure 
using code like the following: 


struct Window *w; 
struct RastPort *usableRastPort; 


/* and then, after your Window is initialized... */ 
usableRastPort —= w->RastPort; 
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You can also get the RastPort from the layer structure, if you are not using Intuition. 


Drawing Individual Pixels 


You can set a specific pixel to a desired color by using a statement like this: 


int result; 
result = WritePixel( &myRastPort, x, y); 


WritePixel() uses the primary drawing pen and changes the pixel at that x,y position to the 


desired color if the x,y coordinate falls within the boundaries of the RastPort. A value of 0 is 


returned if the write was successful; a value of -1 is returned if x,y was outside the range of the 
RastPort. 


Reading Individual Pixels 


You can determine the color of a specific pixel with a statement like this: 


int result; 
result = ReadPixel( &myRastPort, x, y); 


ReadPixel() returns the value of the pixel color selector (from 0 to 255) at the specified x,y 


location. If you specify an x,y outside the range of your RastPort, this function returns a 
value of -1. 


Drawing Lines 


Two functions are associated with line drawing: Move() and Draw(). Move() simply moves 
the cursor to a new position. It is like picking up a drawing pen and placing it at a new loca- 
tion. This function is executed by the statement: 


Move( &myRastPort, x, y); 


Draw() draws a line from the current x,y position to a new x,y position specified in the state- 
ment itself. The drawing pen is left at the new position. This is done by the statement: 


Draw( &myRastPort, x, y); 
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Draw() uses the pen color specified for FgPen. Here is a sample sequence that draws a red 
line from location (0,0) to (100,50). Assume that the value in color register 2 represents red. 


SetAPen( &myRastPort, 2); /* make primary pen red */ 
Move( &myRastPort, 0, 0); /* move to new location */ 
Draw( &myRastPort, 100,50); /* draw to a new location */ 


Caution: If you attempt to draw a line outside the bounds of the BitMap, using 
the basic initialized RastPort, you may crash the system. You must either do your 
own software clipping to assure that the line is in range, or use the layer library. 
Software clipping means that you need to determine if the line will fall outside your 
BitMap before you draw it. 


Drawing Patterned Lines 


To turn the example above into a patterned line draw, simply add the following statement: 


SetDrPt( &myRastPort, Oxaaaa); 


Now all lines drawn appear as dotted lines. To resume drawing solid lines, execute the 
statement: 


SetDrPt( &myRastPort, -1); 


Drawing Multiple Lines with a Single Command 


You can use multiple Draw() statements to draw connected line figures. If the shapes are all 
definable as interconnected, continuous lines, you can use a simpler function, called 


PolyDraw(). PolyDraw() takes a set of line endpoints and draws a shape using these points. 
You call PolyDraw() with the statement: 


PolyDraw( &myRastPort, count, arraypointer); 


PolyDraw() reads an array of points and draws a line from the current pen position to the 
first, then a connecting line to each succeeding position in the array until count points have 
been drawn. This function uses the current drawing mode, pens, line pattern, and write mask 
specified in the target RastPort; for example: 
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SHORT linearray[ ] = { 
3,3, 
15,3, 
15,15, 
3,15, 
3,3 
}3 


PolyDraw( &myRastPort, 5, &linearray (0); 


draws a rectangle, using the five defined pairs of x,y coordinates. 


Area-fill Operations 


Assuming that you have properly initialized your RastPort structure to include a properly ini- 
tialized AreaInfo, you can perform area fill by using the functions described in this section. 


AreaMove() tells the system to begin a new polygon, closing off any other polygon that may 
already be in process by connecting the end-point of the previous polygon to its starting point. 
AreaMove() is executed with the statement: 


AreaMove( &myRastPort, x, y); 


AreaDraw/() tells the system to add a new vertex to a list that it is building. No drawing 
takes place when AreaDraw() is executed. It is executed with the statement: 


AreaDraw( &myRastPort, x, y); 


AreaEnd() tells the system to draw all of the defined shapes and fill them. When this function 
is executed, it obeys the drawing mode and uses the line pattern and area pattern specified in 
your RastPort to render the objects you have defined. Note that to fill an area, you do not 
have to AreaDraw() back to the first point before calling AreaEnd(). AreaEnd() automati- 
cally closes the polygon. AreaEnd() is executed with the following statement: 


AreaEnd( &myRastPort); 


Here is a sample program segment that includes the ArealInfo initialization. It draws a pair of 
disconnected triangles, using the currently defined FgPen, BgPen, AOlPen, DrawMode, 
LinePtrn, and AreaPtrn: 


WORD areabuffer[250]; 
struct RastPort *rp; 
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struct TmpRas tmpras; 
struct AreaInfo myArealInfo; 


InitArea(&myArealInfo, areabuffer, 100); 
rp- >ArealInfo = &myArealInfo; 
rp->TmpRas = InitTmpRas( &tmpras, AllocRaster(320,200), RASSIZE(320,200); 


/* Area routines need a temporary raster buffer at least as large as the 

* largest object to be drawn. If a single task uses multiple RastPorts, 

* it is sometimes possible to share the same TmpRas structure among 

* multiple RastPorts. Multiple tasks, however, cannot share a TmpRas, 
* as each task won’t know when another task has a drawing partially 

* completed. 


*/ 

AreaMove{( rp, 0,0 ); 
AreaDraw( rp, 0,100); 
AreaDraw( rp, 100,100); 


AreaMove( rp, 50,10); 
AreaDraw/( rp, 50,50); 
AreaDraw( rp, 100,50); 
AreaEnd (rp ); 
If you had executed the statement “SetOPen( &myRastPort, 3)” in the area-fill example, then 


the areas that you had defined would have been outlined in pen color 3. To turn off the outline 
function, you have to set the RastPort Flags variable back to 0 by: 


#include ” graphics/gfxmacros.h” 
BNDRYOFF(&myRastPort); 


Otherwise, every subsequent area-fill or rectangle-fill operation will use the outline pen. 


Caution: If you attempt to fill an area outside the bounds of the BitMap, using the 
basic initialized RastPort, it may crash the system. You must either do your own 
software clipping to assure that the area is in range, or use the layer library. 
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Flood-fill Operations 


Flood fill is a technique for filling an arbitrary shape with a color. The Amiga flood-fill routines 


can use a plain color or do the fill using a combination of the drawing mode, FgPen, BgPen, 
and the area pattern. 


There are two different modes for flood fill: 


o In outline mode you specify an x,y coordinate, and from that point the system searches 
outward in all directions for a pixel whose color is the same as that specified in the area 
outline pen. All horizontally or vertically adjacent pixels not of that color are filled 
with a colored pattern or plain color. The fill stops at the outline color. Outline mode 
is selected when the mode variable is a 0. 


o In color mode you specify an x,y coordinate, and whatever pixel color is found at that 
position defines the area to be filled. The system searches for all horizontally or verti- 
cally adjacent pixels whose color is the same as this one and replaces them with the 
colored pattern or plain color. Color mode is selected when the mode variable is a 1. 


You use the Flood() routine for flood fill. The syntax for this routine follows. 


Flood( rp, mode, x, y); 


where 
rp is a pointer to the RastPort 
x,y is the starting coordinate in the BitMap 


mode tells how to do the fill 


The following sample program fragment creates and then flood-fills a triangular region. The 
overall effect is exactly the same as shown in the preceding area-fill example above, except that 
flood-fill is slightly slower than area-fill. Mode 0 (fill to a pixel that has the color of the outline 
pen) is used in the example. 
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oldAPen = myRastPort.FgPen; 

SetAPen( &myRastPort, myRastPort.AOl]Pen); 
/* using mode 0 */ 

/* triangular shape */ 

Move( &myRastPort, 0, 0); 

Draw( &myRastPort, 0, 100); 

Draw( &myRastPort, 100, 100); 

Draw( &myRastPort, 0,0); /* close it */ 


SetAPen( &myRastPort, oldAPen); 
Flood(&myRastPort, 0, 10, 50); 


This example saves the current FgPen value and draws the shape in the same color as 


AO}Pen. Then FgPen is restored to its original color so that FgPen, BgPen, DrawMode, 
and AreaPtrn can be used to define the fill within the outline. 


Rectangle-fill Operations 


The final fill function, RectFill(), is for filling rectangular areas. The form of this function 
follows: 


RectFill( rp, xmin, ymin, xmax, ymax); 
where 


xmin and ymin 
represent the upper left corner of the rectangle 


xmax and ymax 
represent the lower right corner of the rectangle 


rp points to the RastPort that receives the filled rectangle 


Rectangle-fill uses FgPen, BgPen, AO]Pen, DrawMode and AreaPtrn to fill the area you 
specify. Remember that the fill can be multicolored as well as single- or two-colored. 


The following three sets of statements perform exactly the same function: 
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/* area-fill a rectangular area */ 
SetAPen(rp,1); 

SetOPen(rp,3); 
AreaMove(rp,0,0); 
AreaDraw(rp,0,100); 
AreaDraw(rp,100,100); 
AreaDraw(rp,100,0); 
AreaEnd(rp); 


/* flood-fill a rectangular area */ 
SetAPen(rp,3); 

SetOPen(rp,3); 

Move(rp,0,0); 

Draw/(rp,0,100); 
Draw/(rp,100,100); 
Draw/(rp,100,0); 

Draw(rp,0,0); 

SetAPen(rp,1); 
Flood(rp,0,50,50); 

/* rectangle-fill a rectangular area */ 
SetAPen(rp,1); 

SetOPen(rp,3); 
Rectfill(rp,0,0,100,100); 


Not only is the RectFill() routine the shortest, it is also the fastest to execute. 


Data Move Operations 


The graphics support functions include several routines for simplifying the handling of the rec- 
tangularly organized data that you would encounter when doing raster-based graphics. These 
routines do the following: 
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o Clear an entire segment of memory 

o Set araster to a specific color 

o Scroll a subrectangle of a raster 

o Draw a pattern ‘“‘through a stencil” 

o Extract a pattern from a bit-packed array and draw it into a raster 
o Copy rectangular regions from one bit-map to another 

o Control and utilize the hardware-based data mover, the blitter 


The following sections cover these routines in detail. 


Clearing a Memory Area 


For memory that is accessible to the blitter (that is, internal CHIP memory), the most efficient 
way to clear a range of memory is to use the blitter. You use the blitter to clear a block of 
memory with the statement: 


BltClear( memblock, bytecount, flags); 


where memblock is a pointer to the location of the first byte to be cleared, and bytecount is 
the number of bytes to set to zero. 


This command accepts the starting location and count and clears that block to zeros. For the 
meanings of settings of the flags variable, see the summary page for this routine in the “Library 
Summaries”’ appendix. 


Setting a Whole Raster to a Color 


You can preset a whole raster to a single color by using the function SetRast(). A call to this 
function takes the following form: 


SetRast( RastPort, pen); 


where 
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RastPort 
is a pointer to the RastPort you wish to use 


pen 


is the pen value that you wish to fill that RastPort 


Scrolling a Sub-rectangle of a Raster 


You can scroll a sub-rectangle of a raster in any direction—up, down, left, right, or diagonally. 
To perform a scroll, you use the ScrollRaster() routine and specify a dx and dy (delta-x, 
delta-y) by which the rectangle image should be moved towards the (0,0) location. 

As a result of this operation, the data within the rectangle will become physically smaller by the 
size of delta-x and delta-y, and the area vacated by the data when it has been cropped and 


moved is filled with the background color (color in BgPen). 


Here is the syntax of the ScrollRaster() function: 


ScrollRaster( rp, dx, dy, xmin, ymin, xmas, ymax ); 
where 
rp is a pointer to a RastPort 


dx, dy 


are the distances (positive, 0, or negative) to move the rectangle 


xmin, xmax, ymin, ymax 
specify the outer bounds of the sub-rectangle 


Here are some examples that scroll a sub-rectangle: 


/* scroll down 2 */ 
ScrollRaster(&my RastPort,0,2,10,10,50,50); 


/* scroll right 1 */ 
ScrollRaster(&myRastPort,1,0,10,10,50,50); 
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Drawing through a Stencil 


The routine BltPattern() allows you to change only a very selective portion of a drawing area. 
Basically, this routine lets you define the rectangular region to be affected by this drawing 
operation and a mask of the same size that defines how that area will be affected. 


Figure 1-17 shows an example of what you can do with BltPattern(). The 0 bits are 
represented by blank rectangles; the 1 bits by filled-in rectangles. 


Mask contains: Result of BitPattern(): Drawing area contains: 





Figure 1-17: Example of Drawing Through a Stencil 
In the “Result”? drawing, the lighter squares show where the target drawing area has been 
affected. Exactly what goes into the drawing area where the mask has 1’s is determined by your 
FgPen, BgPen, DrawMode, and AreaPtrn. 
The variables that control this function are: 
rastport a pointer to the drawing area 


mask a pointer to the mask (mask layout explained below) 


xl, maxx  upover left corner x, and lower right corner x 
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yl, maxy upper left corner y, and lower right corner y 


bytecnt number of bytes per row for the mask (must be an even number of bytes) 


You call BltPattern() with: 


BltPattern( rastport, mask, xl, yl, maxx, maxy, bytecnt) 


The mask parameter is a rectangularly organized, contiguously stored pattern. This means 


that the pattern is stored in linearly increasing memory locations stored as (maxy - yl) rows of 
bytecnt bytes per row. 


Note: These patterns must obey the same rules as BitMaps. This means that they must con- 
sist of an even number of bytes per row. For example, a mask such as: 


0100001000000000 
0010010000000000 
0001 1 00000000000 
0010010000000000 


is stored in memory beginning at a legal word address. 


Extracting from a Bit-packed Array 


You use the routine BltTemplate() to extract a rectangular area from a source area and place 
it into a destination area. Figure 1-18 shows an example. 
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Array start: 
line end+1 





Character starts n-bits in from starting point 
on the left edge of the array. 


Figure 1-18: Example of Extracting from a Bit-Packed Array 


If the rectangular bit array is to be represented as a rectangle within a larger, rectangularly 
organized bit array, the system must know how the larger array is organized. This allows the 
system to extract each line of the object properly. For this extraction to occur properly, you 
need to tell the system the modulo for the array. The modulo is the value that must be added 


to the address pointer so that it points to the correct word in the next line in this rectangularly 
organized array. 


Figure 1-19 represents a single bit-plane and the smaller rectangle to be extracted. The modulo 
in this instance is 4, because at the end of each line, you must add 4 to the address pointer to 
make it point to the first word in the smaller rectangle. 


<t——_—_—_———- Larger source 
bit-plane image 


Smaller rectangle 


to be extracted. 





Figure 1-19: Modulo 
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Note that the modulo value must be an even number of bytes. 


BltTemplate() takes the following arguments: 


source the source pointer for the array 
srcX source X (bit position) in the array at which the rectangle begins 
srcMod source modulo so it can find the next part of the source rectangle 


destRastPort the destination RastPort 
destX, destY destination x and y, showing where to put the rectangle 


sizeX,sizeY size x and y, indicating how much data to move 


You call BltTemplate() with: 


Blt Template( source, srcX, srcMod, destRastPort, destX, destY, sizeX, sizeY ); 


Blt Template() uses FgPen, BgPen, DrawMode and Mask to place the template into the 
destination area. This routine differs from BltPattern() in that only a solid color is deposited 
in the destination drawing area, with or without a second solid color as the background (as in 
the case of text). Also, the template can be arbitrarily bit-aligned and sized in x. 


Copying Rectangular Areas 


Two routines copy’ rectangular areas from one_ section of chip memory to 
another: BltBitMap() and ClipBlit(). BltBitMap() is the basic routine, taking BitMaps as 
part of its arguments. It allows you to define a rectangle in a source region and copy it to a 


destination area of the same size elsewhere in memory. This routine is often used in graphics 
rendering. 


ClipBlit() takes most of the same arguments, but it works with the RastPorts and layers. 
Before ClipBlit() moves data, it looks at the area from which and to which the data is being 
copied (RastPorts, not BitMaps) and determines if there are overlapping areas involved. It 


then splits up the overall operation into a number of bit maps to move the data in the way you 
request. 


Here is a sample call to ClipBlit(). This call is used in an image editor to transfer a rectangu- 
lar block of data from the screen to a back-up area. 
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ClipBlit( &rastport, /* on-screen area */ 
x,y, /* upper left corner of rectangle */ 
&undorastport, /* screen editor can undo things, has 
* a RastPort specifically for undo */ 


0,0, /* upper left corner of destination */ 
SIZEx ,SIZEy /* how big is the rectangle * / 
minterm); 


The minterm variable is an unsigned byte value whose leftmost 4 bits represent the action to 
be performed during the move. This routine uses the blitter device to move the data and can 
therefore logically combine or change the data as the move is made. The most common opera- 
tion is a direct copy from source area to destination, which is the hex value CO. 


You can determine how to set the minterm variable by using the logic equations shown in 
table 1-5. 


Table 1-5: Minterm Logic Equations 


Logic Term Logic Term Included 
in Leftmost 4 Bits in Final Output 
8 BC 
4 BC 
2 BC 
1 BC 


Source B contains the data from the source rectangle, and source C contains the data from the 
destination area. If you choose bits 8 and 4 from the logic terms (CO), in the final destination 


area you will have data that occurs in source B only. Thus, CO means a direct copy. The logic 
equation for this 1s: 


BC + BC=B(C +C)=B 


Logic equations may be used to decide on a number of different ways of moving the data. For 
your convenience, a few of the most common ones are listed in table 1-6. 
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Table 1-6: Some Common Logic Equations for Copying 


Hex 
Value Mode 
30 Replace destination area with inverted source B. 
50 Replace destination area with inverted version 


of original of destination. 
60 Put B where C is not, put C where B is not (cookie cut). 


80 Only put bits into destination where there is 
a bit in the same position for both source 
and destination (sieve operation). 


Refer to the listing for BItBitMap() in the “Library Summaries” index. 


Accessing the Blitter in a Multitasking Environment 


To use the blitter, you must first be familiar with how its registers control its operation. This 
topic is covered thoroughly in the Amzga Hardware Reference Manual and is not repeated here. 


Four routines may be used to gain access to the blitter: 


o OwnBlitter() allows your task to obtain exclusive use of the blitter. Note, however, 
that the system uses the blitter extensively for disk and display operation. While your 
task is using the blitter, many other system processes will be locked out. Therefore, use 
it only for brief periods and relinquish it as quickly as possible, using DisownBlitter(). 


o DisownBlitter() returns the device to shared operation. 


o QBlit() and QBSBlit() let your task queue up requests for the use of the blitter on a 
non-exclusive basis. You share the blitter with system tasks. 


You provide a data structure called a bltnode (blitter node). The system can use this structure 
to link blitter usage requests into a first-in, first-out (FIFO) queue. When your turn comes, 


your own blitter routine can be repeatedly called until your routine says it is finished using the 
blitter. 


Two separate queues are formed. One queue is for the QBlit() routine. You use QBlit() when 
you simply want something done and you do not necessarily care when it happens. This may 
be the case when you are moving data in a memory area that is not currently being displayed. 
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The second queue is maintained for QBSBlit(). QBS stands for “queue-beam-synchronized” 
blitter operations. QBSBlit() forms a beam-synchronized FIFO. When the video beam gets to 
a predetermined position, your routine is called. Beam synchronization takes precedence over 
the simple FIFO. This means that if the beam sync matches, the beam-synchronous blit will be 
done before the non-synchronous blit in the first position in the queue. You might use 
QBSBlit() to draw into an area of memory that is currently being displayed to modify memory 


that has already been ‘“‘passed-over’”’ by the video beam. This avoids display flicker as an area 
is being updated. 


The input to each routine is a pointer to a bltnode data structure. The required items of the 
data structure are: 


o A pointer to a bltnode 
o A pointer to a function to perform 
o <A beamsync value (used if this is a beamsync blit) 


o A status flag indicating whether the blitter control should perform a ‘‘clean-up”’ routine 
when the last blit is finished 


o The address of the clean-up routine if the status flag states that it should be used 


The bltnode data structure is contained in the include file hardware/blit.h. Here is a copy of 
that data structure, followed by details about the items you must initialize: 


struct bltnode 


{ 


struct bltnode *n; 
int (*function)( ); 
char stat; 

short blitsize; 

short beamsync; 

int (*cleanup)( ); 


}3 
The contents of bltnode are as follows: 


struct bltnode *n; 


This is a pointer to the next bltnode, which, for most applications will be zero. You 
should not link bltnodes together. This is to be performed by the system by way of a 
separate call to QBlit() or QBSBIit(). 


58 Graphics Primitives 


int (*function)( ); 


This position is occupied by the address of a function that the blitter queuer will call 
when your turn comes up. Your routine must be formed as a subroutine, with an RTS 
at the end. Using the C-language convention, the returned value will be in DO (C 
returns its value by the return(value) statement). 


If you return a nonzero value, the system will call your routine the next time the blitter 
is done until you finally return 0. This is to allow you to maintain control over the 
blitter; for example, it allows you to handle all five bit-planes if you are blitting an 
object that spans that number of planes. For display purposes, if you are blitting mul- 
tiple objects and then saving and restoring the background, you must be sure that all 
planes of the object are positioned before another object is overlaid. This is the reason 
for the lockup in the blitter queue; it allows all work per object to be completed before 
going on to the next one. 


Actually, the system tests the status codes for a condition of KQUAL or NOTEQUAL. 
When the C language returns the value of 0, it sets the status codes to EQUAL. When 
it returns a value of -1, it sets the status codes to NOTEQUAL, so they would be com- 
patible. Functions (*function)()) that are written for QBlit() and QBSBIlit() are not 
normally written in C. They are usually written in assembly language, as they then can 
take advantage of the ability of the queue routines to pass them parameters in the sys- 
tem registers. The register passing conventions for these routines are as follows: 


o Register AO receives a pointer to the system hardware registers so that all hardware 
registers can be referenced as an offset from that address. 


o Register Al contains a pointer to the current bltnode. You may have queued up 
multiple blits, each of which perhaps uses the same blitter routine. You can access 
the data for this particular operation as an offset from the value in Al. A typical 
user of these routines will precalculate the hardware register values that are stuffed 
into the registers and, during the routine, simply stuff them. For example, you can 
create a new structure such as the following: 
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struct myblit { 

struct bltnode; /* make this new structure 

* compatible with the bltnode 

* by making it the first element */ 
short bltcon1; /* contents to be stuffed into 

*« blitter control register 1 */ 
short fwmask,lwmask; 

/* first and last word masks */ 
short bltmdc, bltmdb, bltmda; 

/* modulos for sources a, b,and c */ 
char *bltpta, *bltptb, *bltptc; 

/* pointer to source data for sources */ 


}3 


Other forms of data structures are certainly possible, but this should give you the gen- 
eral idea. 


char stat; 


Tells the system whether or not to execute the clean-up routine at the end. This byte 
should be set to CLEANUP (0x40) if cleanup is to be performed. If not, then the 
bltnode cleanup variable can be zero. 


short beamsync; 


The value that should be in the VBEAM counter for use during a beam-synchronous 
blit before the function() is called. 


The system cooperates with you in planning when to start a blit in the routine 
QBSBIlit() by not calling your routine until, for example, the video beam has already 
passed by the area on the screen into which you are writing. This is especially useful 
during single buffering of your displays. There may be time enough to write the object 
between scans of the video display. You will not be visibly writing while the beam is 
trying to scan the object. This avoids flicker (part of an old view of an object along 
with part of a new view of the object). 


int (*cleanup)(); 


The address of a routine that is to be called after your last return from the QBIlit() 
routine. When you finally return a zero, the queuer will call this subroutine (ends in 
RTS or return()) as the clean-up. Your first entry to the function may have dynami- 
cally allocated some memory or may have done something that must be undone to 
make for a clean exit. This routine must be specified. 
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User Copper Lists 


The Copper coprocessor allows you to produce mid-screen changes in certain hardware registers 
in addition to changes that the system software already provides. For example, it is the Copper 


that allows the Amiga to split the viewing area into multiple draggable screens, each with its 
own independent set of colors. 


To create your own mid-screen (or mid-Intuition-Screen) effects on the system hardware regis- 
ters, you provide “user Copper lists” that can be merged into the system Copper lists. 


In the ViewPort data structure there is a pointer named UCopIns. If this pointer value is 
non-NULL, it points to a user Copper list that you have dynamically allocated and initialized to 


contain your own special hardware-stuffing instructions. You allocate a user Copper list by an 
instruction sequence such as the following: 


struct UCopList *cl; 
cl = (struct UCopList *) 
AllocMem(sizeof(struct UCopList), MEMF_PUBLIC | 
MEMF_CHIP | MEMF_CLEAR); 
Once this pointer to a user Copper list is available, you can use it with system macros 
(graphics/gfxmacros.h) to instruct the system what to add to its own list of things for the 
Copper to do within a specific ViewPort. 


The file graphics/gfrmacros.h provides the following three macro functions that implement user 
Copper instructions. 


CWAIT waits for the video beam to reach a particular horizontal and vertical position. Its 
format follows: 


CWAIT(uc, v, h) 
where 
uc is the pointer to the Copper list 


vis the vertical position for which to wait, specified relative to the top of the ViewPort. 
The legal range of values is from 0 to 261. 


his the horizontal position for which to wait. The legal range of values is from 0 to 223 
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CMOVE installs a particular value into a specified system register. Its format follows: 


CMOVE(uc, reg, value) 


where 
uc is the pointer to the Copper list 
reg is the register to be affected, specified in this form form: ‘‘custom.register’’ (see 


hardware/custom.h) 


CEND terminates the user Copper list. Its format follows: 


CEND(uc) 
where uc is the pointer to the user Copper list. 


Executing any of the user Copper list macros causes the system to dynamically allocate special 
data structures called intermediate Copper lists that are linked into your user Copper list (the 
list to which cl points) describing the operation. When you call the function 
MakeVPort(&view, &viewport) as shown in the section called ‘Forming A Basic Display,” 
the system uses all of its intermediate Copper lists to sort and merge together the real Copper 
lists for the system (LOFCprList and SHFCprList). 


When your program exits, you must return to the system all of the memory that you allocated 
or caused to be allocated. This means that you must return the intermediate Copper lists, as 


well as the user Copper list data structure. Here are two different methods for returning this 
memory to the system. 


/* Returning memory to the system if you have NOT 
* obtained the viewport from Intuition. */ 


FreeVPortCopLists(&viewport); 


/* Returning memory to the system if you HAVE 
* obtained the viewport from Intuition. */ 


CloseScreen(screen); /* Intuition only */ 
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The example program below shows the use of user Copper lists under Intuition. 


/* User-Copper-Lists Demo Program ... changes the background color 
* In mid-screen. 


a 


#define WINDOWGADGETS (WINDOWSIZING|WINDOWDRAG| 
WINDOWDEPTH|WINDOWCLOSE) 

#define WWIDTH 120 

#define WHEIGHT 90 

#define MAXINT OxFFFFFFFF 


#include ” exec/types.h” 

#include ”exec/memory.h” 
#include <graphics/gfxmacros.h > 
#include <graphics/copper.h> 
#include ” intuition /intuition.h” 
#include <hardware/custom.h > 


extern struct Window *OpenWindow(); 
extern struct Screen +*OpenScreen(); 


long IntuitionBase—0; 
long GfxBase—0; 


/* use the 40/80 column font for this test */ 
struct TextAttr TestFont = { 
*topaz.font”, 8, 0, 0 


i 


struct NewScreen ns = { 


0, 0, /* start position */ 
320, 200, 4,  /* width, height, depth */ 
0, 1, /* detail pen, block pen */ 
0, /* viewing mode */ 


CUSTOMSCREEN, /* screen type */ 
&TestFont, /* font to use */ 

”Test Screen”, /* default title for screen */ 

NULL /* pointer to additional gadgets */ 


hi 


extern struct Custom custom; 
/* provides a way to get to the base of the custom chips * / 
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main() 


{ 


struct Window *w; /* pointer to a Window */ 
struct RastPort *rp; /* pointer to a RastPort */ 
struct ViewPort *vp; /* pointer to a ViewPort */ 
struct UCopList *cl; /* user Copper list and a pointer to it. */ 


struct Screen *screen; 

GfxBase = OpenLibrary(” graphics. library”, 0); 
if (GfxBase —— NULL) 

{ 


} 


IntuitionBase = OpenLibrary(” intuition.library”, 0); 
if (IntuitionBase == NULL) 


exit(1000); 


CloseLibrary(GfxBase); 
exit(2000); 
} 


screen = OpenScreen(&ns); 
if(!screen) 


{ 
} 


else 


{ 


goto cleanup; 


vp = &screen- > ViewPort; 
rp = &screen- >RastPort; 


} 


/* v1.1 initialization, just use CINIT for v1.2 */ 


/* In this case, although WE allocated the memory for the user Copper list, 
* the SYSTEM (Intuition) deallocates it when the custom screen is closed. 
* Therefore there is no corresponding FreeMem() in this sample program. 


cl = AllocMem(sizeof(struct UCopList), MEMF_PUBLIC|MEMF_CLEAR); 


CWAIT(cl1,100,0); /* wait till middle of screen */ 
CMOVE(cl,custom.color|0|,0OxFFF); /* change background color */ 
CEND(cl); 


/* Programmer can affect ANY of the system registers that the Copper has access to 
* (see the Amiga Hardware Reference Manual) in this way. Simply note that the 

* system may already be using these registers in some manner and that most of 

* the system registers are either read-only or write-only, so you’ll have to be 
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* careful about what you are trying to affect. 
7 


vp->UCopIns = cl; 

Delay(50); /* wait one second before changing anything */ 
/* Now force a remake of the Copper list for all screens. */ 
RethinkDisplay(); 


Delay(100); 
CloseScreen(screen); 
cleanup: 
CloseLibrary(Intuition Base); 
CloseLibrary(GfxBase); 


} 


/* end of main() */ 


Advanced Graphics Examples 


DUAL-PLAYFIELDS EXAMPLE 


This example is almost identical to the single-playfield demonstration program earlier in this 
chapter. It has been adapted to show a dual-playfield display with objects drawn in both 
playfields. The single playfield wrote directly into the screen’s memory. This example adds a 
RastPort so that rectangle-fill routines can be used. 


#include <exec/types.h > 
#include <graphics/gfx.h> 
#include <graphics/gfxbase.h > 
#include <hardware/dmabits.h> 
#include <hardware/custom.h> 
#include <graphics/gfxmacros.h > 
#include <graphics/rastport.h > 
#include <graphics/view.h > 
#include <exec/exec.h> 


#define DEPTH 2 

#define WIDTH 320 

#define HEIGHT 200 

#define NOT_ENOUGH_MEMORY -1000 
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struct View v; 

struct ViewPort vp; 

struct ColorMap *cm; /* pointer to ColorMap structure, dynamic alloc */ 
struct RasInfo ri; 

struct BitMap b; 


/* added a second RasInfo for dual.playfield */ 
struct RasInfo ri2; 
/* added a second BitMap for dual.playfield */ 
struct BitMap b2; 


short 1,),k,n; 
struct ColorMap *GetColorMap(); 
struct GfxBase *GfxBase; 


/* black, red, green, blue, 
* ignored, ignored, ignored, ignored, 
* (transparent), purple, lime green, mauve */ 


USHORT colortable[| = { 

0x000, Oxf00, OxOf0O, OxOOf, 

0,0,0,0, 

O, 0Ox495, 0x62a, Oxf9c 
} 
/* Nobody will see center set of 4 colors in this case because only two planes 
* and dual-playfield mode. (In dualpf mode, colors 0-7 are dedicated to 
* playfield 1, and 8-15 to playfield number 2. So since only 2 planes in each 
* playfield, colors 4-7 and 12-15 won’t even get used in this example) 


*/ 
UWORD ¥xcolorpalette; 
/* added RastPorts for both bitmaps */ 


struct RastPort rp, rp2; 
struct View *oldview; /* save and restore old View */ 


main() 


{ 


GfxBase = (struct GfxBase *)OpenLibrary(” graphics.library” ,O); 
if (GfxBase == NULL) exit(1); 


InitView(&v); _//* initialize View */ 


v.ViewPort = &vp;_ /* link View into ViewPort */ 
InitVPort(&vp); /* init ViewPort */ 
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/* now specify critical characteristics */ 
vp.DWidth = WIDTH; 
vp.DHeight = HEIGHT; 
vp.RasInfo = &ri; 
vp.Modes = DUALPF | PFBA ;  /* dual-playfield mode */ 


/* init bit map (for RasInfo and RastPort) */ 

InitBitMap( &b, DEPTH, WIDTH,HEIGHT); 
/* (init RasInfo) */ 

n.BitMap = &b; 

/* align upper left corners of display 

* with upper left corner of drawing area */ 

ri.RxOffset = 0; 

n.Ry Offset = 0; 


/* 2K 2k 2K 2k ok 2k 2 aK 2K 2k 2k oc 2K 2 ok 2k ok 2k i 2K 2c i 2 ok ok 2 2 2k ok oe kK 2k 2k 2 oie ok 2 2k oe 2c ke 2 kc 2 ofc 2 2k 2c 2 oie ok 2c 2 oe 2 ok 2k ok + / 
/* changed here for dual playfields */ 

InitBitMap( &b2, DEPTH, WIDTH, HEIGHT); 

ri.Next = &ri2; 

ri2.BitMap = &b2; 

ri2.RxOffset = 0; 

n2.RyOffset = 0; 

ri2.Next = 0; 


/* Ke 2k 2k 2k ke 2k 2 2 2 2c 2 ke 6K 2 2K 2K 2 a 2K 2 2 2 2 2 2 2 2 2 2k 2 2 a 2k kc kee kc 2c 2c 2k 2 2 2 2K EK cc 2c ke 2c 2 2 2 2 2 2 2 ok kc oc 2 a 2c 2 2k + / 


/* (init color table) */ 
cm = GetColorMap(12); —/* 12 entries, since dual playfields */ 
colorpalette = cm->ColorTable; 
for(i=0; 1<12; i++) 


{ 
} 


*colorpalette++ = colortable|il; 


/* copy my colors into this data structure */ 
vp.ColorMap = cm; _ /* link it with the ViewPort */ 


/* allocate space for BitMap */ 
for(i=0; i<DEPTH; i++) 


b.Planes[i] = (PLANEPTR)AllocRaster( WIDTH,HEIGHT); 
if(b.Planes[i] =— NULL) exit(NOT_ENOUGH_MEMORY); 


b2.Planes|i] = (PLANEPTR)AllocRaster(WIDTH,HEIGHT); 
if(b2.Planes[{i] =— NULL) exit(NOT_ENOUGH_MEMORY); 


/* Initialize the RastPorts and link them to the bitmaps */ 
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InitRastPort(&rp); 
InitRastPort(&rp2); 
rp.BitMap = &b; 
rp2.BitMap = &b2; 


MakeVPort( &v, &vp ); /* construct Copper instr (prelim) list */ 


MrgCop( &v ); /* merge prelim lists together into a real 
* Copper list in the View structure. */ 
SetRast(&rp,0); /* simpler form of setting drawing area to 0 */ 


SetRast(&rp2,0); 


oldview = GfxBase->ActiView; /* save current view to restore later */ 
/* example steals screen from Intuition if started from WBench */ 


Load View(&v); 


/* Now fill some boxes so that user can see something */ 
/* first playfield */ 
SetAPen(&rp,1); 

RectFill( &rp,20,20,200, 100); 
SetAPen(&rp,2); 
RectFill(&rp,40,40,220, 120); 
SetAPen(&rp,3); 
RectFill(&rp,60,60,240, 140); 
/* second playfield */ 
SetAPen(&rp2,1); 

RectFill( &rp2,50,90,245,180); 
SetAPen(&rp2,2); 
RectFill(&rp2,70,70,265, 160); 
SetAPen(&rp2,3); 
RectFill(&rp2,90,10,285,148); 


/* Now tear some holes in the playfield so user can see that foreground 
* area of playfield 2 (called PFB also) is transparent in any area 
* where it has a color value of 0 


+) 


SetAPen(&rp2,0); 
RectFill( &rp2,110,15,130,175); 
RectFill( &rp2,175,15,200,175); 


Delay(300); /* uses AmigaDOS function... delay 5 seconds */ 
LoadView(oldview); /* Put Intuition’s View back again */ 
WaitTOF(); /* wait for Intuition View to return */ 
FreeMemory(); /* and exit gracefully */ 


CloseLibrary(GfxBase); 
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\ /* end of main() */ 


FreeMemory() 


{ /* return user and system-allocated memory to sys manager */ 


for(i=0; i< DEPTH; i++) /* free the drawing area */ 
{ 
FreeRaster(b.Planes|i], WIDTH,HEIGHT); 
FreeRaster(b2.Planes|i|, WIDTH, HEIGHT); 


FreeColorMap(cm); /* free the color map */ 
/* free dynamically created structures */ 
FreeVPortCopLists(&vp); 

FreeCprList(v.LOFCprList); 

return(0); 


HOLD-AND-MODIFY MODE EXAMPLE 


This example demonstrates the Amiga’s hold-and-modify mode, showing at all times a different 
subset of 256 of the 4,096 colors available on the Amiga. At any moment, no two squares are 
the same color. 


PERE BORO EOFS aI III III I ACI I a II IR A AAR. / 
* Rob Peck  -- November 5, 1985 


* Bob Pariseau -- November 10, 1985 (Rework for tutorial) 
JESS dda S SESS S ACHES ESBS ISSA BESS SSSI I IRR E K / 


#include <exec/types.h > 
#include <intuition/intuition.h> 
#include <intuition/intuitionbase.h > 


#define XSIZE 11 /* Color box sizes */ 
#define YSIZE 6 


struct GfxBase *GfxBase; /* Export the library pointers */ 
struct IntuitionBase *IntuitionBase; 


struct RastPort *rp; /* Graphics structures */ 
struct ViewPort *VD; 


struct TextAttr TestFont = 


{ 


*topaz.font”, /* Standard system font */ 


Graphics Primitives 69 


hh) 
struct Window *w; /* Intuition structures */ 
struct Screen *screen; 


struct IntuiMessage *message; 


struct NewScreen ns = { 
O, 0, /* start position */ 
320, 200,6, /* width, height, depth */ 
0, 1, /* detail pen, block pen */ 
HAM, /* Hold and Modify ViewMode */ 
CUSTOMSCREEN, /* screen type */ 
&TestFont, /* font to use */ 
” 256 different out of 4096”,  /* default title for screen */ 
NULL _/* pointer to additional gadgets */ 


i 
struct NewWindow nw = { 
O, 11, /* start position */ 
320, 186, /* width, height */ 
-1, -1, /* detail pen, block pen */ 


MOUSEBUTTONS|CLOSEWINDOW, /* IDCMP flags */ 
ACTIVATE|WINDOWCLOSE,  /* window flags */ 


NULL, /* pointer to first user gadget */ 
NULL, /* pointer to user checkmark */ 
*colors at any given moment”, /* window title */ 
NULL, /* pointer to screen (set below) */ 
NULL, /* pointer to superbitmap */ 


0, 0, 320, 186, /* ignored since not sizeable */ 
CUSTOMSCREEN __/* type of screen desired */ 


iD 


LONG squarecolor|16 * 16], freecolors|4096-(16*16)|; 
SHORT squares|16 * 16]; 
SHORT xpos(16], ypos(16]; 


char *number|| = { 
”0”, mules ah ae i a 74”, Or POG; ea Os ”Q” 
” A”, Peg ee *D”, a ie >” 

bi 


SHORT sStop, cStop, sequence; 
BOOL textneeded; 
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main() 


{ 


ULONG lass; 
USHORT code, 1; 
BOOL wheelmode; 


for(i=0; 1<16; i++) /* establish color square positions */ 
{ 

xpos|i] = (XSIZE + 4) * i + 20; 

ypos|i] = (YSIZE + 3) * i+ 21, 


j 


GfxBase = (struct GfxBase *)OpenLibrary(” graphics.library” , 0); 
if (GfxBase === NULL) exit(100); 


IntuitionBase = (struct IntuitionBase *)OpenLibrary(” intuition. library”, 0); 
if (IntuitionBase == NULL) 


CloseLibrary(GfxBase); 
exit(200); 


} 


screen = (struct Screen *)OpenScreen(&ns); 


if (screen === NULL) 


CloseLibrary(IntuitionBase); 


CloseLibrary(GfxBase); 
exit(300); 
nw.screen = screen; /* open window in our new screen */ 


w = (struct Window *)OpenWindow(&nw); 
if (w = NULL) 


CloseScreen(screen); 
CloseLibrary(IntuitionBase); 
CloseLibrary(GfxBase); 
exit(400); 


j 


vp = &screen- > ViewPort; /* Set colors in screen’s VP */ 
rp = w->RPort; /* Render into the window’s RP */ 


/* Set the color registers: Black, Red, Green, Blue, White */ 
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) 


SetRGB4(vp, 0, 00, 00, 00) 
SetRGB4(vp, 1, 15, 00, 00): 
SetRGB4(vp, 2, 00, 15, 00); 
); 


SetRGB4(vp, 3, 00, 00, 15 
SetRGB4(vp, 4, 15, 15, 15 


) 


} 


SetBPen(rp, 0); /* Insure clean text */ 
textneeded —= TRUE; 
wheelmode = TRUE; //* Start with Color Wheel display */ 


for (i,j) { 
{ /* Process any and all messages in the queue, then update the display 
* colors once, then come back here to look at the queue again. If you 
* see a left-mouse-button-down event, then switch display modes. If you 
* see a Close-Window-gadget event, then clean up and exit the program. 
* NOTE: This is a BUSY LOOP so the colors will cycle as quickly as possible. 
Ke 
/ 


while((message = (struct IntuiMessage *)GetMsg(w- > UserPort)) !== NULL) 


{ 


class = message- > Class; 
code == message- >Code; 
ReplyMsg(message); /* Can’t reply until done using it! */ 


if(class =— CLOSEWINDOW) /* Exit the program */ 


CloseWindow(w); 
CloseScreen(screen); 
CloseLibrary(IntuitionBase); 
CloseLibrary(GfxBase); 
exit(0); 


} 
if(class =— MOUSEBUTTONS && code == SELECTDOWN) /* swap modes */ 
wheelmode = NOT wheelmode; 


SetAPen(rp, 0);  /* Clear the drawing area */ 
SetDrMd(rp, JAM1); 
RectFill(rp, 3, 12, 318, 183); 
textneeded = TRUE; 
} 
} 
if(wheelmode) colorWheel(); else colorFull(); 


j 
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colorFull() /* Display a randomized set of colors */ 
{ 

SHORT sChoice, cChoice, usesquare; 

LONG usecolor; 


if(textneeded) /* First call since mode change? */ 
{ 
prompt(); 
sStop = 255; /* Top of list of squares yet to change */ 
cStop = 4095 - 256; /* Top of list of colors still needing use */ 


for(usecolor=0; usecolor <256; usecolor++) /* Initialize colors */ 


{ 


usesquare — usecolor; 

squares|usesquare| = usesquare; 

squarecolor|usesquare] = usecolor; 

hamBox(usecolor, xpos|usesquare % 16], ypos(usesquare / 16]); 
j 


for(usecolor=256; usecolor< 4095; usecolor++) /* Ones not yet used */ 


{ 
freecolors[usecolor - 256] = usecolor; 
j 
j 


PAROS GOS FSCRIIGIGKIII I I a kkk 
* Randomly choose next square to change such that all squares change color 

* at least once before any square changes twice. squares(0| through squares 

* [sStop| are the square numbers that have not yet changed in this pass. 

* RangeRand(r) is an integer function provided in ”amiga.lib” that produces 


* a random result in the range 0 to (r-1) given an integer r in the range 1 to 65535. 
FSO OOO Soro aa OK OKO Oa I I a i kkk kak ak a ak ak ak ak / 


sChoice = RangeRand(sStop + 1); /* Pick a remaining square */ 
usesquare = squares[sChoice]; /* Extract square number */ 
squares|sChoice] = squares|[sStop];  /* Swap it with sStop slot */ 
squares|sStop| = usesquare; 


if(NOT sStop--) sStop = 255; /* Only one change per pass */ 


PERO OC OIC IC IG OC IGE ICICI aI A ACAI AK a a Aa 
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* Randomly choose new color for selected square such that all colors are 

* used once before any color is used again, and such that no two squares 

* simultaneously have the same color. freecolors|0| through freecolors|cStop]| 

* are the colors that have not yet been chosen in this pass. Note that 

* the 256 colors in use at the end of the previous pass are not available 

* for choice in this pass. 

ASAE IGI RIA A ak ak kak ak ak ak ak / 


cChoice = RangeRand(cStop + 1); 


usecolor = freecolors|cChoice]; 


freecolors[cChoice] = freecolors|cStop]; 
freecolors|[cStop] = squarecolor[usesquare]; 
squarecolor|usesquare] = usecolor; 


if(NOT cStop--) cStop = 4095 - 256; 


hamBox(usecolor, xpos|usesquare % 16], ypos[usesquare / 16}); 


} 


color Wheel() /* Display an ordered set of colors */ 


{ 
SHORT i, j; 


if(textneeded) 
prompt(); 


SetAPen(rp, 2); /* Green pen for green color numbers */ 
Move(rp, 260, ypos{15]+17); 

Text(rp, ”Green”, 5); 

for(i=0; 1<16; i++) 


Move(rp, xpos|i]+3, ypos[{15]+17); 
Text(rp, number|i], 1); 


} 


SetAPen(rp, 3); /* Blue pen for blue color numbers */ 
Move(rp, 4, 18); 
Text(rp, ”Blue”, 4); 
for(i=0; 1<16; i++) 
{ 
Move(rp, 7, ypos(i]+6); 
Text(rp, number|ij, 1); 


} 
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SetAPen(rp, 1); /* Red pen for red color numbers */ 
Move(rp, 271, 100); 
Text(rp, ”Red”, 3); 


sequence = QO; 


} 


SetAPen(rp, 1); /* Identify the red color in use */ 
SetDrMd(rp, JAM2); 

Move(rp, 280, 115); 

Text(rp, number|sequencel, 1); 


for(j=0; }<16; j++) /* Update all of the squares */ 
for(i=0; i<16; i++) 
hamBox((sequence< <8 | i< <4 | j), xpos|i], ypos|j]); 


if(++sequence == 16) sequence=—0; 


} 


prompt() /* Display mode changing prompt */ 
{ 
SetDrMd(rp, JAM2); 
SetAPen(rp, 4); 
Move(rp, 23, 183); 
Text(rp, ” [left mouse button = new mode]”, 30); 
textneeded = FALSE; 


} 


FRB BSR OIRO IG IACOCCA CC CCI IA AE 
* hamBox() -- routine to draw a colored box in Hold and Modify mode. Draws a 
* box of size XSIZE by YSIZE with an upper left corner at (x,y). The 

desired color is achieved in 3 steps on each horizontal line of the box. 

First we set the red component, then the green, then the blue. We 

achieve this by drawing a vertical line of Modify-Red, followed by a 

vertical line of Modify-Green, followed by a rectangle of Modify-Blue. 

Note that the resulting color for the first two vertical lines depends 

upon the color(s) of the pixels immediately to the left of that 

line. By the time we reach the rectangle we are assured of getting 

(and maintaining) the desired color because we have set all 3 

components (R, G, and B) straight from the bit map. 

JeSC OOO SSS ACSC SCS SOCKS ECG SIO SG EGAI ISIE IIIA / 
hamBox(color, x, y) 

LONG color, x, y; 


{ 


* &* &€* &* &* &* & FF 
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SHORT oc; 
SetDrMd(rp, JAM1); /* Establish Drawing Mode in RastPort */ 


c==((color & Oxf00)> >8); /* Extract desired Red color component. */ 
SetAPen(rp, c + 0x20); /* Hold G, B from previous pixel. Set R=n. */ 
Move(rp, x, y); 

Draw(rp, x, y+ YSIZE); 


Xa 

c=((color & Oxf0)>>4); /* Extract desired Green color component. */ 
SetAPen(rp, c + 0x30); /* Hold R, B from previous pixel. Set G=n. */ 
Move(rp, x, y); 

Draw(rp, x, y+ YSIZE); 


a 

c=(color & Oxf); /* Extract desired Blue color component.*/ 
SetAPen(rp, c + 0x10); /* Hold R, G from previous pixel. Set B=n. */ 
RectFill(rp, x, y, x + XSIZE-2, y+-YSIZE); 
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Chapter 2 


Layers 


The layers library enables you to create displays containing overlapping display elements. This 
chapter describes the layers library routines and how you use them in creating graphics. 


Introduction 


The layers library contains routines that do the following: 
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o Multiplex a BitMap among various tasks by creating “layers” in the BitMap 


o Create separate writable BitMap areas, some portions of which may be in the common 
(perhaps on-screen) BitMap, and some portions in an obscured area. In two modes, 
called smart-refresh and superbitmap, graphics are rendered into both the obscured and 
the non-obscured areas. 


o Move, size or depth-arrange the layers, bringing obscured segments into a non-obscured 
area, 


Tasks can create layers in a common BitMap and then output graphics to those layers without 
any knowledge that there are other tasks currently using this BitMap. 


To see what the layers library provides, you need only look at the Intuition user interface, as 
used by numerous applications on the Amiga. The windows that Intuition creates are based, in 


part, on the underlying strata of the layers library. You can find more details about Intuition 
in the book titled Intuition: The Amiga User Interface. 


If you wish, you can use the layers library directly to create your own windowing system. The 
layers library takes care of the difficult things, that is, the bookkeeping jobs that are needed to 
keep track of where to put which bits. Once a layer is created, it may be moved, sized, depth- 
arranged or deleted using the routines provided in this library. In performing their rendering 


operations, the graphics routines know how to use the layers and only draw into the correct 
drawing areas. 


DEFINITION OF LAYERS 


The internal definition of the layers resembles a set of clipping rectangles in that a drawing area 
is split into a set of rectangles. A clipping rectangle is a rectangular area into which the graph- 
ics routines will draw. Some of the rectangles are visible; some are invisible. If a rectangle is 
visible, the graphics can draw directly into it. If a rectangle is obscured by an overlapping 
layer, the graphics routine may possibly draw into some other memory area. This memory area 
must be at least large enough to hold the obscured rectangle so the graphics routines can, on 
command, expose the obscured area. 


The layers library manages interactions between the various layers by using a data structure 


called Layer_Info. Each major drawing area, called a BitMap (which all windows share), 
requires one Layer_Info data structure. 


You may choose to split the viewing area into multiple parts by providing multiple independent 
ViewPorts. If you use the layers library to subdivide each of these parts into layers (effectively 
providing windows within these subdivisions), you must provide one Layer_Info structure for 
each of these parts. 
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TYPES OF LAYERS SUPPORTED 


The layers library supports four types of layers: 


o Swmple Refresh 


No back-up area is provided. Instead, when an obscured section of the layer'is exposed 
to view, the routine using this layer is told that a ‘‘refresh” of that area is in order. 
This means that the program using this layer must redraw those portions of its display 
that are contained in the previously obscured section of the layer. All graphics render- 
ing routines are “‘clipped’’ so that they will only draw into exposed sections of the layer. 


o Smart Refresh 
The system provides one or more back-up areas into which the graphics routines can 
draw whenever a part of this layer is obscured. 

o Superbitmap 


There is a single back-up area, which is permanently provided to store what is not in 
the layer. The back-up area may be larger than the area that is actually shown in the 
on-screen BitMap. 


o Backdrop 


A backdrop layer always appears behind all other layers that you create. The current 
implementation of backdrop layers prevents them from being moved, sized, or depth- 
arranged. 


Layers Library Routines 


The layers library contains the routines shown below: 
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Purpose Routine 


Allocating a Layer_Info NewLayerInfo() 
structure 
Deallocating a Layer_Info DisposeLayerInfo() 
structure 
Intertask operations LockLayer(), UnLockLayer(), 


LockLayers(), UnlockLayers(), 
LockLayerInfo(), UnlockLayerInfo() 


Creating and deleting layers CreateUpfrontLayer(), 
CreateBehindLayer(), 


DeleteLayer() 
Moving layers MoveLayer() 
Sizing layers SizeLayer() 
Changing a viewpoint ScrollLayer() 
Reordering layers BehindLayer, UpfrontLayer() 
Determining layer position WhichLayer() 


Sub-layer rectangle operations SwapBitsRastPortClipRect() 


INITIALIZING AND DEALLOCATING LAYERS 


The function NewLayerInfo() allocates and initializes a Layer_Info data structure and allo- 
cates some extra needed memory for the 1.1 release. After the call to NewLayerInfo(), you 
can use the layer operations described in the following paragraphs. 


The function DisposeLayerInfo() deallocates a Layer_Info structure that was allocated with 
a call to NewLayerInfo() and frees the extra memory that was allocated. 


Note: Prior to the current 1.1 release, Layer_Info structures were initialized with the 
InitLayers() function. For backwards compatibility, you can still use this function with newer 
software. For optimal performance, however, you should call FattenLayerInfo() to allocate 
the needed extra memory and ThinLayerInfo() to return the memory to the system free-list. 
Failure to deallocate memory will result in loss of that available memory. 
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INTERTASK OPERATIONS 


This section shows the use of the routines LockLayerInfo(), UnlockLayerInfo(), 
LockLayer(), UnlockLayer(), LockLayers(), and UnlockLayers(). 


LockLayerInfo() and UnlockLayerInfo() 


You create layers by using the routines CreateUpFrontLayer() and CreateBehindLayer(). 
If multiple tasks are all trying to create layers on the same screen or ViewPort, each task will 
be trying to affect the same data structures while creating its layers. The Layer_Info data 
structure controls the layers. LockLayerInfo() ensures that the Layer_Info data structure 
remains intact and tasks can obtain this exclusive access. 


LockLayerInfo() grants exclusive access to the locking task. If some other task has the 
Layer_Info locked, the call will block until the lock succeeds. 


LockLayer() and Unlocklayer() 


If a task is making some changes to a particular layer, such as resizing it or moving it, the task 
must inhibit the graphics rendering into the layer. LockLayer() blocks graphics output once 
the current graphics function has completed. The other task goes to sleep only if it attempts to 
draw graphics. LockLayer() returns exclusive access to the layer once other tasks, including 
graphics, are finished with this layer. 


UnlockLayer() frees the locked layer for other operations. 


If more than one layer must be locked, then these LockLayer() calls must be surrounded by 
LockLayerInfo() and UnLockLayerlInfo(). This is to prevent deadlock situations. 


LockLayers() and UnlockLayers() 


Sometimes it is necessary to lock all layers at the same time. For example, under Intuition, a 
rubber-band box is drawn when a window is being moved or sized. To draw such a box, Intui- 
tion must stop all graphics rendering to all windows (and associated layers) so that it can draw 
a line using the graphics complement drawing mode. If other graphics draw over this line, it 
would not be possible for Intuition to erase it again, using a subsequent complement operation 
over the same line. Thus LockLayers() is used to lock all layers in a single command. 
UnlockLayers() releases the layers. 
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You can simulate LockLayers() by calling LockLayer() for each layer in the LayerList. 


However, in that case, you must call LockLayerInfo() before and UnlockLayerInfo() after 
each LockLayer() call. 


CREATING AND DELETING LAYERS 


CreateUpFrontLayer() creates a layer that is in front of all other layers. Intuition uses this 
function to create certain types of new windows, as well as other Intuition components. 


CreateBehindLayer() creates a layer that is behind all other layers. Intuition uses this func- 
tion to create a new “Backdrop” window. 


Each of the routines that create layers return a pointer to a layer data structure (shown in the 
include file graphics/layers.h). 


Note: When you create a layer, the system automatically creates a RastPort to go along with 
it. Because a RastPort is specified by the drawing routines, if you use this layer’s RastPort, 
you will draw into only the area that you have designated on the screen for this layer. See also 
the topic called “The Layer’s RastPort’’ below. 


DeleteLayer() is used to remove a layer from the layer list. It is one of the functions used by 
Intuition to close a window. 


For these functions, you need to perform LockLayerInfo() and UnlockLayerInfo(), because 
you need to access the Layer_Info structure itself. 


MOVING LAYERS 


MoveLayer() moves a layer to a new location. When you move a layer, the move command 
affects the list of layers that is being managed by the Layer_Info data structure. The system 
locks the Layer_Info for you during this operation. 


SIZING LAYERS 


The SizeLayer() command changes the size of a layer by leaving the coordinates of the upper 
left corner the same and modifying the coordinates of the lower right corner of the layer. The 
system locks the Layer_Info for you during this operation. 
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CHANGING A VIEWPOINT 


ScrollLayer() is for superbitmap layers only. This command changes the portion of a super- 
bitmap that is shown by a layer. An analogy is a window in a wall. If the homeowner does not 
like the view he sees from a particular window, he might either change what he sees by planting 
trees (that is, new graphics rendering) or he might decide to move the window to see another 
part of the great outdoors (changing the portion of the superbitmap shown by a layer). You 
must provide a superbitmap; the ScrollLayer() command repositions the smaller layer against 
the larger superbitmap, thus showing a different part of it. 


Because the layer size and on-screen position do not change while this operation is taking place, 
it is not necessary to lock the Layer_Info data structure. However, it is necessary to prevent 
graphics-rendering operations from drawing into this layer or its associated superbitmap while 


ScrollLayer() is performing the repositioning. Thus, the system locks the layer for you while 
this operation is taking place. 


REORDERING LAYERS 


BehindLayer() and UpfrontLayer() are used, respectively, to move a layer behind all other 
layers or in front of all other layers. BehindLayer() also considers any backdrop layers, mov- 
ing a current layer behind all others except backdrop layers. The system performs 
LockLayers() for you during this operation. 


DETERMINING LAYER POSITION 


If the viewing area has been separated into several layers, you may wish to find out which layer 
is topmost at a particular x,y coordinate. For example, Intuition does this while keeping track 
of the mouse position. When you move the mouse into one of the windows and click the left 
button, Intuition feeds the current x,y coordinate to WhichLayer(). In_ return, 
WhichLayer() tells Intuition which layer has been selected, and thus it knows with which win- 
dow you wish to work. 


If you wish to be sure that no task changes the sequence of layers (by using UpfrontLayer(), 
BehindLayer(), CreateUpFrontLayer(), DeleteLayer(), MoveLayer() or SizeLayer() ) 
before your task can use this information, call LockLayerInfo() before calling WhichLayer(). 
Then, after receiving and using the information that WhichLayer() delivers, you can call 
UnlockLayerInfo(). In this way, you will assure that you are acting on data that was true as 
of the moment it was received. 


Layers 83 


SUB-LAYER RECTANGLE OPERATIONS 


The SwapBitsClipRectRastPort() routine is for users who do not want to worry about clip- 
ping rectangles. The need for this routine goes a bit deeper than that. It is a routine that actu- 


ally enables the menu operations of Intuition to function much more quickly than they would if 
this routine were not provided. 


Consider the case where there are several windows open on an Intuition screen. If you wish to 
produce a menu, there are two ways to do it: 


o Create an up-front layer with CreateUpfrontLayer(), then render the menu in it. 
This could use lots of memory and require a lot of (very temporary) ‘“‘slice-and-dice”’ 
operations to create all of the clipping rectangles for the existing windows and so on. 

o Use SwapBitsClipRectRastPort(), directly on the screen drawing area: 

o Render the menu in a back-up area off the screen, then lock all of the on-screen 


layers so that no task can use graphics routines to draw over your menu area on 
the screen. 


o Next, swap the on-screen bits with the off-screen bits, making the menu appear. 
o When you finish with the menu, swap again and unlock the layers. 


The second rendering method is faster and leaves the clipping rectangles and most of the rest of 
the window data structures untouched. 


Notice that all of the layers must be locked while the menu is visible. Any task that is using 
any of the layers for graphics output will be halted while the menu operations are taking place. 


If, on the other hand, the menu is rendered as a layer, no task need be halted while the menu is 
up because the lower layers need not be locked. It is a tradeoff decision that you must make. 


The Layer’s RastPort 


When you create a layer, you automatically get a RastPort. The pointer to the RastPort 1s 
contained in the layer data structure and can be retrieved typically by the statement: 


rp = layer->rp; /* copy the pointer from the layer structure 
* into a local pointer for further use */ 
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Using this RastPort, you can draw anywhere into the layer’s defined rectangle. Location (0,0) 
is the coordinate location for the upper left corner of the rectangle, and location (xmax, ymax) 
is the lower right corner. If you try to draw to any location outside of this coordinate system, 
the graphics routines will clip the drawing to the inside boundaries of this area. 


The type of layer you specify by the Flags variable determines the other facilities the layer pro- 
vides. The following paragraphs describe the types of layers —simple refresh, smart refresh, 
superbitmap, and backdrop—and the flags you set for the type you want. Note that the three 
layer-type Flags are mutually exclusive. That is, you cannot specify more than one layer-type 


flag —LAYERSIMPLE, LAYERSMART, LAYERSUPER. 


SIMPLE REFRESH LAYER 


When you draw into the layer, any portion of the layer that is visible (not obscured) will have 
its drawing rendered into the common BitMap of the viewing area. 


If another layer operation is performed that causes part of a simple refresh layer to be obscured 
and then exposed, you must restore the part of the drawing that your application rendered into 
the obscured area. 


Simple refresh has two basic advantages: 


o It uses no back-up area to save drawing sections that cannot be seen anyway (and 
therefore saves memory). 


o When an application tries to restore the layer by performing a full-layer redraw, 
(sandwiched between a BeginUpdate(), EndUpdate() pair), only those damaged 


areas are redrawn, making the operation very time efficient. 


Its disadvantage is that the application needs to watch to see if its layer needs refreshing. This 
test can be performed, typically, by a statement set such as the following: 


refreshstatus = layer->Flags & LAYERREFRESH; 
if (refreshstatus != 0) refresh(layer); 


Note: Applications using Intuition typically get their refresh notifications as event messages 
passed through an Intuition Direct Communications Message Port (IDCMP). 
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SMART REFRESH LAYER 


If any portion of the layer is hidden by another layer, the bits for that obscured portion are ren- 
dered into a back-up area. With smart refresh layers, the system handles all of the refresh 
requirements except when the layer is made larger. Its disadvantage is the additional memory 
needed to handle this automatic refresh. 


SUPERBITMAP LAYER 


A superbitmap layer is similar to a smart refresh layer. It too has a back-up area into which 
drawings are rendered for currently obscured parts of the display. However, it differs from 
smart refresh in that: 


o The back-up BitMap is user-supplied, rather than being allocated dynamically by the 
system. 


o The back-up BitMap may be larger than the area of this BitMap that is currently 
showing within the current size of this layer. 


To see a larger portion of a superbitmap in the on-screen layer, you use SizeLayer(). To see a 
different portion of the superbitmap in the layer, you use ScrollLayer/(). 


When the graphics routines perform your drawing commands, part of the drawing appears in 
the common BitMap (the on-screen portion). Any drawing outside the layer itself is rendered 
into the superbitmap. When it is time to scroll or size the layer, the layer contents are copied 
into the superbitmap, the scroll or size positioning is modified, and the appropriate portions are 
then copied back into the layer. 


BACKDROP LAYER 


Any layer can be designated a backdrop layer. You can turn off the backdrop flag temporarily 
and allow a layer to be depth-arranged. Then by restoring the backdrop flag, you can again 
inhibit depth-arrangement operations. 


You change the backdrop flag typically by the statements: 


layer->Flags &= LAYERBACKDROP; /* turn off the backdrop bit */ 
layer->Flags |= LAYERBACKDROP; /* turn on the backdrop bit */ 


86 Layers 


Using the Layers Library 


The following is a step-by-step example showing how the layers library can be used in your pro- 
grams. Note that the Intuition software, which is part of the system as well, manages many of 
these items for you. The example below can be started up under Intuition, but it requires that 
the Amiga be reset in order to exit the program. 

The example program explains the individual parts separately, then merges the parts into a sin- 
gle working example. This simple example produces three rectangles on the screen: one red, 


one green, and one blue. Each rectangle is rendered as a rectangle-fill of one of three smart 
layers created for the example. 


OPENING THE LAYERS LIBRARY 


Like all library routines, the layers library must be opened before it can be used. This is done 
typically by the following code: 


struct LayersBase *LayersBase; 


LayersBase = (struct LayersBase *)OpenLibrary(” layers.library” ,O); 
if(LayersBase —==—= NULL) 


exit(NO_LAYERS_LIBRARY_FOUND); 


OPENING THE GRAPHICS LIBRARY 


Because the example uses various graphics library functions as well as the layers library, you 
must also open the graphics library with the following code: 


struct GfxBase *GfxBase; 


GfxBase = (struct GfxBase *)OpenLibrary(”graphics.library” ,O); 
if(GfxBase == NULL) 


exit(NO_GRAPHICS_LIBRARY_FOUND),; 
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CREATING A VIEWING WORKSPACE 


You can create a viewing workspace by using the primitives InitVPort(), InitView/(), 
MakeVPort(), MrgCop(), and LoadView(). See the “Graphics Example” section in chapter 
1, ‘Graphics Primitives.” You add the following statements: 


struct Layer_Info *li; 
li=NewLayerInfo(); 


This provides and initializes a Layer_Info data structure with which the system can keep track 
of layers that you create. 


CREATING THE LAYERS 


You can create layers in this common bit map by calling CreateUpfrontLayer() (or 
CreateBehindLayer() ), with a sequence such as the following. The Flags value in this exam- 
ple is LAYERSMART (see graphics/clip.h in the “Include Files’? appendix for all other flag 
values). This sequence requests construction of a smart refresh layer. 


#define FLAGS LAYERSMART 

struct BitMap b; 

struct Layer_Info i; 

struct RastPort *rp[3];_ /* allocate a RastPort pointer for each layer */ 
struct Layer *layer[3]; | /* allocate a layer pointer for each layer */ 


/* Layer_Info, common BitMap, x1,y1,x2,y2, 
* flags = 0 (smart refresh), null pointer to superbitmap */ 


layer[0] = CreateUpfrontLayer(&li,&b,20,20,100,80,FLAGS,NULL); 


layer[1] = CreateUpfrontLayer(&li,&b,30,30,110,90, FLAGS,NULL); 
layer([2] = CreateUpfrontLayer(&li,&b,40,40,120,100,FLAGS,NULL); 


/* if not enough memory, can’t continue the example * / 


if(layer(O0]—==—NULL || layer[1]—==—NULL || layer[2)——NULL) exit(3); 
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GETTING THE POINTERS TO THE RASTPORTS 


Each layer pointer data structure contains a pointer to the RastPort that it uses. Here is the 
assignment from the layer structure to a set of local pointers: 


for(i=0; i<3; i++) 


rp[i] = layer[i]->rp; 


USING THE RASTPORTS FOR DISPLAY 


Here are the rectangle-fill operations that create the display: 


for(i=0; i<3; i++) 


SetAPen(rp|i],i+1); 
SetDrMd(rp{i],JAM1); 
RectFill(rp[i],0,0,80,50); 


} 


If you perform an UpfrontLayer() or BehindLayer() command prior to the Delay() shown 
in the complete example below, all of the data contained in each layer is retained and correctly 
rendered automatically by the layers library. This is because these are all smart-refresh layers. 
If you change the example to use a Flags value of LAYERSIMPLE, and then perform 
UpfrontLayer() or BehindLayer(), the obscured portions of the layers, now exposed, contain 
only the background color. This illustrates that simple-refresh layers may have to be redrawn 
after layer operations are performed. 


LAYERS EXAMPLE 


Here is the complete example, which is a compilation of the complete example in chapter 1 and 
the pieces given above. Sections of the example that differ from those shown in the chapter 1 
example are indicated through comments to show the additions adding the layers hbrary 
demonstration. 
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PERO OOO AOE GE ISOS G SSA RIOR I Gk 
* This example shows how to use the layers.library. Certain functions are not 
* available in the system software prior to the release of version 1.1. Therefore, 


* this example can be compiled only if your C-disk supports version 1.1 or beyond. 
FCCC AOI G a OES ARBOR A IIE a / 


#include ”exec/types.h” 

#include ” graphics/gfx.h” 

#include ”hardware/dmabits.h” 

#include ”hardware/custom.h” 

#include ”hardware/blit.h” 

#include ” graphics/gfxmacros.h” 

#include ” graphics /copper.h” 

#include ” graphics/view.h” 

# include ” graphics/gels.h” 

#include ” graphics/regions.h” 

#include ” graphics/clip.h” 

#include ”exec/exec.h” 

#include ” graphics/text.h” 

#include ” graphics/gfxbase.h” 

/* oA: added for layers support ARR Ad a kk kk kk > / 
#include ” graphics/layers.h” 

#include ” graphics/clip.h” 

/* HK added for layers SUPPOTt >>I AK I kK a a a a + / 


#define DEPTH 2 

#define WIDTH 320 

#define HEIGHT 200 

#-define NOT_ENOUGH_MEMORY -1000 


/* construct a simple display */ 

#define FLAGS LAYERSMART 

/* dynamically created RastPorts from the calls to CreateUpfrontLayer */ 
struct RastPort *rp|[3}; /* RastPort for each layer */ 


struct ColorMap *GetColorMap(); 
struct GfxBase *GfxBase; 


SHORT boxoffsets|] = { 802, 2010, 3218 }; 

/* black, red, green, blue */ 
USHORT colortable{] = { 0x000, Oxf00, OxOf0, Ox00f }; 
long LayersBase; 
extern struct Layer *CreateUpfrontLayer(); 
extern struct Layer_Info *NewLayerInfo(); 


90 Layers 


main() 


{ 


struct View *oldview; /* save pointer to old View so can go back to sys */ 
struct View v; 

struct ViewPort vp; 

struct ColorMap *cm; /* pointer to ColorMap structure, dynamic alloc */ 
struct RasInfo ri; 

struct BitMap b; 

short 1,),k,n; 

struct Layer_Info *hi; 

struct Layer *layer(3}; 


GfxBase = (struct GfxBase *)OpenLibrary(” graphics.library” ,O); 
if (GfxBase === NULL) exit(1); 


LayersBase = OpenLibrary(” layers.library” ,0); 
if(LayersBase === NULL) exit(2); 


oldview = GfxBase->ActiView; /* save current View, go back later */ 
/* example steals screen from Intuition */ 


li = NewLayerlInfo(); /* get a Layer_Info structure */ 
if(li == NULL) exit(100); 


/* not needed if gotten by NewLayerlnfo InitLayers(li); 
FattenLayerlnfo(li); */ 


InitView(&v); /* initialize View * / 
v.ViewPort = &vp;_ /* link View into ViewPort */ 
Init VPort( &vp); /* init ViewPort */ 


/* now specify critical characteristics */ 
vp.DWidth = WIDTH; 
vp.DHeight —= HEIGHT; 
vp.RasInfo = &ni; 
/* init BitMap (for RasInfo and RastPort) */ 
InitBitMap(&b, DEPTH, WIDTH,HEIGHT); 
ri1.BitMap = &b; /* (init RasInfo) */ 
ri.RxOffset = 0; /* align upper left corners of display 
* with upper left corner of drawing area */ 
ri.Ry Offset = 0; 
ri.Next = NULL; 
/* (init color table) */ 
vp.ColorMap = GetColorMap(4); /* four entries, since only two planes deep */ 
colorpalette = (UBYTE *)cm->ColorTable; 
/* copy my colors into this data structure */ 
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LoadRGBA4(vp,colortable,4); 


/* allocate space for BitMap */ 


b.Planes(i] = (PLANEPTR)AllocRaster(WIDTH,HEIGHT); 
if(b.Planes[i] === NULL) exit NOT_ENOUGH_MEMORY),; 
BltClear(b.Planes|i], RASSIZE(width,height),0); 


} 

MakeVPort( &v, &vp ); /* construct Copper instr (prelim) list */ 

MrgCop( &v ); /* merge prelim lists together into a real 
* Copper list in the View structure. */ 

Load View(&v); 


/* now fill some boxes so that user can see something */ 


/* Layer_Info, common BitMap, x,y,x2,y2, 

* flags = 0 (simple refresh), null pointer to superbitmap */ 
layer|O] = CreateUpfrontLayer(li,&b,5,5,85,65,FLAGS,NULL); 
if(layer(O] === NULL) goto cleanup]; 


layer|1] = CreateUpfrontLayer(li,&b,20,20,100,80,FLAGS,NULL); 
if(layer{1] —— NULL) goto cleanup2; 


layer|2] = CreateUpfrontLayer(li,&b,45,45,125,105, FLAGS, NULL); 
if(layer|2] =— NULL) goto cleanup3; 


fori=0; 1<3;i++) /* layers are created, now draw to them */ 
{ 
rp|i] = layer(i|->rp; 
SetAPen(rpii],i+1); 
SetDrMd(rp|i],JAM1); 
RectFill(rp|i],0,0,79,59); 
} 
SetAPen(rp(0],0); 
Move(rp/(0],5,30); 
Text(rp|0],” Layer 0” 7); 


SetAPen(rp|1],0); 
Move(rp(1],5,30); 
Text(rp({1],” Layer 1”,7); 


SetAPen(rp(2],0); 
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Move(rp/[2],5,30); 
Text(rp|2],” Layer 2”,7); 


Delay(100); /* two seconds before first change */ 
BehindLayer(li,layer(2}); 


Delay(100); /* another change two seconds later */ 
UpfrontLayer/(li,layer(0}); 


for(i=0; 1<30; i++) 
{ 
MoveLayer(li,layer|1],1,3); 
Delay(10); /* wait .2 seconds (uses DOS function) */ 


} 


cleanups: 
Load View(oldview); /* put back the old View */ 
DeleteLayer(li,layer[2}); 
cleanup2: 
DeleteLayer(li,layer|1]); 
cleanuplI: 
DeleteLayer(li,layer|0}]); 


DisposeLayerInfo(li); 


/* return user and system-allocated memory to sys manager */ 
for(i=0; i<DEPTH; i++) /* free the drawing area */ 
FreeRaster(b.Planes{i], WIDTH,HEIGHT); 
FreeColorMap(cm); /* free the color map */ 
/* free dynamically created structures */ 
FreeVPortCopLists( &vp); 
FreeCprList(v.LOFCprList); 
return(0); 


CloseLibrary(GfxBase); 


/* end of main() */ 
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Clipping Rectangle List 


When you perform the various graphics drawing routines, you will notice that the routines draw 
into Intuition windows, even though the windows might be partially or totally obscured on the 
screen. This is because the layer library functions split the drawing area to provide lists of 
drawing areas that the graphics drawing can use for its operations. 


In particular, the layer library functions split the windows into rectangles. You need only con- 
cern yourself with a single overall RastPort that contains the description of the complete area 
that you are managing. When either you or Intuition use the layer library, the graphics rou- 
tines will be able to tell how the drawing area is split and where rendering can occur. 


The set of rectangles comprising the layer is known as a clipping rectangle list (ClipRect struc- 
ture). A clipping rectangle is a rectangular area into which the graphics routines will draw. All 
drawing that would fall outside of that rectangular area is clipped (not rendered). 


DAMAGE LIST 


For a smart-refresh window, the system automatically generates off-screen buffer spaces, essen- 
tially linked into the clipping rectangle list. Thus, parts of the display that are on the screen 
are rendered into the on-screen drawing area, and parts of the display that are obscured are 
drawn into a back-up area. When segments are exposed, the back-up area information is 
brought to view automatically during the routines UpfrontLayer() and BehindLayer(), as 
well as during MoveLayer(). 


For a simple-refresh window however, any section of a drawing area that is not covered in the 
chipping rectangle list is not drawn into by the graphics routines. When obscured areas are 
exposed, they will not contain any graphics rendering at all. As the system creates and moves 
layers in front of such simple-refresh windows, the layers library keeps track of the rectangular 
segments that have not been drawn and are therefore not part of any automatically saved 
back-up areas. This list of non-drawn areas is called a DamageList. 


REPAIRING THE DAMAGE 


When you receive a REFRESH event from Intuition for a simple refresh window, you are being 
told that Intuition, through the layers library, has done something to change the portions of 
your window that are exposed to view. In other words, there is likely to be a blank space where 
there is supposed to be some graphics. 
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To update only those areas that need updating, you call BeginUpdate(). BeginUpdate() 
saves the pointer to the current clipping rectangles. It also installs in the layer structure a 
pointer to the set of ClipRects generated from the DamageList. In other words, the graphics 
rendering routines see only those rectangular spaces that need to be updated and refuse to draw 
into any other spaces within this layer. If, for example, there are only one or two tiny rectan- 
gles that need to be fixed, the graphics routines can ignore all but these spaces and repair them 
very quickly and efficiently. To repair the layer, you ask the graphics routines to redraw the 


whole layer, but the routines use the new clipping rectangle list (that is, the damage list) to 
speed the process. 


To complete the update process call EndUpdate(), to restore the original ClipRect list. 


Regions 


Regions are rectangles that, when combined, can become part of a DamageList. The library 


graphics.lubrary contains several support routines for regions. Among these are routines for the 
following operations: 


Operation Routine 


Creating and deleting regions NewRegion(), DisposeRegion() 


Changing a region AndRectRegion(), OrRectRegion, 
XorRectRegion() 
Clearing a region ClearRegion() 


Basically, the region commands let you construct a custom DamageList, which you can use 
with your graphics rendering routines. With this list, you can selectively update a custom-sized, 


custom-shaped part of your display area without disturbing any of the other layers that might 
be present. 


CREATING AND DELETING REGIONS 


NewRegion() allocates and initializes a new data structure that may be thought of as a blank 
painter’s easel. 


If this new region is to be used as the basis for a DamageList, and you asked the graphics rou- 
tines to draw something through this DamageList, nothing would be drawn as there is nothing 
in the region. The region that you produce can be thought of as patches of canvas. A new 
region has no canvas. 
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Because a region is dynamically created by using NewRegion(), the procedure 
DisposeRegion() is provided to return the memory to the system when you have finished with 


it. Note that not only the region structure is deallocated; so are any rectangles that have been 
linked into it. 


CHANGING A REGION 


OrRectRegion() modifies a region structure by or’ing a clipping rectangle into the region. 
This has an effect similar to adding a rectangle of canvas to the easel. If you now exercise the 
drawing routines, the rendering will occur in the areas where the region has been or’ed (canvas 
rectangle has been added) and will be inhibited elsewhere. 


AndRectRegion() modifies a region structure by and’ing a clipping rectangle into the region. 
This has an effect similar to using the rectangle as an outline for a position on the easel. Any 
area of canvas that falls outside this outline is clipped and discarded. 


XorRectRegion() applies the rectangle to the region in an exclusive-or mode. That is, wher- 
ever there is no canvas, canvas is applied to the easel. Wherever there is canvas present within 


the rectangle, a hole is created. Thus it is a combination of OrRectRegion() and 
AndRectRegion() in a single application. 


CLEARING A REGION 


While you are performing various types of selective drawing area updates, you may wish to do 
some of your graphics rendering with one form of region, and some with a different form of 
region. You can perform ClearRegion() to go from one form back to a fresh, empty region. 


Then you can begin again to compose yet another modified region for the next drawing func- 
tion. 


USING REGIONS 


The region routines typically are used in a sequence like the following: 
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struct Region *r; 
struct Rectangle *rectl, *rect2, rect3; 


r = NewRegion(); 


OrRectRegion(rect1, r); /* add a rectangle */ 
AndRectRegion(rect3, r); /* patch a rectangle */ 
XorRectRegion(rect2, r); /* weird patch */ 


/* in this section of code: 
* 1. Save current pointer to DamageList for the layer you wish to affect. 


* 2. Equate the region address (r) to the DamageList pointer in the 
* layer structure. 


* 3. Perform whatever drawing functions you wish into this layer. 
* 4, Restore the original DamageList pointer. 


*/ 


DisposeRegion(r); 


The drawing will only occur in those areas of the drawing area that you have specified should 


be updated. Graphics rendering is often made faster this way, because not all of the area need 
be updated. 


A typical sequence using ClearRegion() might be: 


struct Region *r; 
struct Rectangle *rectl, *rect2, rect3; 
struct Layer_Info *1li; 


r = NewRegion(); 
OrRectRegion(rectl, r); 
OrRectRegion(rect2, r); 


(swap in as a damage list) 
BeginUpdate(li); 

(draw, draw, draw something) 
End Update(li); 


(restore original damage list) 


ClearRegion(r); 
AndRectRegion(rect3, r); 


(swap, draw, restore) 


DisposeRegion(r); 
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SAMPLE APPLICATION FOR REGIONS 


For example, assume that you are producing a display that requires a view through a fence. 
You can create this “‘slats” effect by using regions, as follows: 


1. Create a new region. 


2. Create several rectangles representing the open areas of the slats in the fence. 
3. Or these into the region. 

4, Save the DamageList pointer in the affected layer so it can be restored later. 
5. Copy the region address into DamageList pointer. 

6. Draw the scene into the entire layer using the graphics. 

7. Restore the original DamageList pointer. 


8. Dispose of the region. 


Here is a sample application. It is based on the sample layers library program shown above. 
For brevity, the comments have been stripped out except where new material, pertinent to 
regions, has been inserted. 


/* SIMPLE REGIONS EXAMPLE.... DRAW BEHIND A FENCE */ 
/* Certain layers.library routines are used herein that are not 
* available until Amiga C compiler version 1.1 and beyond. */ 


#include <exec/types.h > 
#include <graphics/gfx.h > 
#include <hardware/dmabits.h> 
#include <hardware/custom.h > 
#include <graphics/gfxmacros.h > 
#include <graphics/regions.h > 
#include <graphics/clip.h> 
#include <graphics/text.h > 
#include <hardware/blit.h > 
#include <graphics/gfxbase.h > 
#include <graphics/copper.h > 
#include <graphics/gels.h > 
#include <graphics/rastport.h > 
#include <graphics/view.h > 
#include <exec/exec.h> 
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#include <graphics/layers.h > 


#define FLAGS LAYERSIMPLE 
extern struct Layer *CreateUpfrontLayer(); 


struct GfxBase *GfxBase; 
long LayersBase; 


#define DEPTH 2 

#define WIDTH 320 

#define HEIGHT 200 

#define NOT_ENOUGH_MEMORY -1000 


struct ColorMap *GetColorMap(); 


USHORT colortable({| = { 0x000, Oxf00, Ox0f0, Ox00f }; 
/* black, red, green, blue */ 


extern struct Layer_Info *NewLayerInfo(); 


main() 

{ 
struct View *oldview; 
struct View v; 
struct ViewPort vp; 
struct ColorMap *cm; 
struct RasInfo ri; 
struct BitMap b; 
struct RastPort *rp; /* one RastPort for one layer */ 
short 1,j,k,n; 
UBYTE *displaymem; 
UWORD ¥*colorpalette; 


struct Layer_Info *h; 
struct Layer *layer; /* one layer pointer */ 


extern struct Region *NewRegion(); 

struct Region *rgn; /* one region pointer */ 

struct Rectangle rect|14]; /* some rectangle structures */ 
struct Region *oldDamageList; 

SHORT x,y; 


GfxBase = (struct GfxBase *)OpenLibrary(” graphics. library” ,O); 
if (GfxBase === NULL) exit(1); 
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LayersBase = OpenLibrary({” layers. library” ,0); 
if(LayersBase === NULL) exit(2); 


oldview = GfxBase- > ActiView; 


li = NewLayerlInfo(); /* v1.1 code only */ 
Init View( &v); 

v.ViewPort = &vp; 

InitVPort(&vp); 

vp.DWidth = WIDTH; 

vp.DHeight = HEIGHT; 

vp.RasInfo = &ri, 
InitBitMap(&b, DEPTH, WIDTH,HEIGHT); 
n.BitMap = &b; 

ri.RxOffset = 0; 

nl.RyOffset = 0; 

ri. Next = NULL; 

em = GetColorMap(4); 

colorpalette = (UWORD *)cm->ColorTable; 
for(i=0; 1<4; i++) 

{ 


*colorpalette++ = colortable{il; 


vp.ColorMap = cm; 
for(i=0; i< DEPTH; i++) 


b.Planes[i] = (PLANEPTR)AllocRaster(WIDTH,HEIGHT); 
if(b.Planes|i] =— NULL) exit(NOT_ENOUGH_MEMORY); 


BltClear(b.Planes|i], RASSIZE(WIDTH,HEIGHT,0); 
} 


MakeVPort( &v, &vp ); 
MrgCop( &v ); 


Load View(&v); 
layer = CreateUpfrontLayer(li, &b,0,0,200,140, FLAGS,NULL); 
if(layer—=—NULL) exit(3); 


rp = layer->rp; 


SetAPen(rp,3); 
RectFill(rp,0,0,199,139); /* show the layer itself */ 


j=10; /* initialize the rectangles */ 
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for(i=0; 1<10; i++) 


{ 
rect(i].MinX = j; 
rect|i]|.MaxX = j + 8; 
rect|i]|.MinY = 20, 
rect|i]. MaxY = 120; 
] += 16; 
} 
rgn = NewRegion(); /* get a new region to use */ 


if(rgn == NULL) exit(4); 


for(i=0; 1<14; i++) 
OrRectRegion(rgn,&rect/i]); 


oldDamageList = layer- >DamageList; 
layer- >DamageList = rgn; 


BeginU pdate(layer); 


/* here insert the drawing routines to draw something behind the slats */ 
x= 4 y = 10; 
SetAPen(rp,0); 
SetDrMd(rp,JAM1); 
RectFill(rp,0,0,199, 139); 
SetAPen(rp,1); 
SetBPen(rp,0); 
SetDrMd(rp,JAM2); 
for(i=0; i<14; i++) 
{ 
Move(rp, x, y); 
Text(rp,” Behind A Fence” ,14); 
x+=4 y += 9; 


EndUpdate(layer); 
layer- >DamageList = oldDamageList; 
DisposeRegion(rgn); 


Delay(300); 


DeleteLayer(li, layer); 
DisposeLayerInfo(li); 


Load View(oldview); 
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/* return user and system-allocated memory to sys manager */ 
for(i=0; i< DEPTH; i++)/* free the drawing area */ 
FreeRaster(b.Planes|i], WIDTH,HEIGHT); 
FreeColorMap(cm); /* free the color map */ 
/* free dynamically created structures */ 
FreeVPortCopLists( &vp); 
FreeCprList(v.LOFCprList); 
return(0); 


CloseLibrary(GfxBase); 


} /* end of main() */ 
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Chapter 3 


Animation 


Introduction 


The graphics animation routines let you define images by specifying various characteristics of 
graphic objects, such as the following: 
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o Height 


o Width 
o Colors 
o Shape 


o Position in the drawing area 

o How to draw the object 

o How to move the object 

o How the object interacts with other elements 
The objects you define are called GELS (for “graphic elements”). You can draw GELS into or 
onto a background display of some type. The graphics animation routines operate on a list of 


GELS to produce a list of instructions that cause the system to draw the GELS in the manner 
you have specified. 


PREPARING TO USE GRAPHICS ANIMATION 


Because the animation routines have been designed to interact with a background display, you 
must first make sure that such a display is already defined. 


To define a display with which the GELS can interact, you define View, ViewPort, and 
RastPort structures. For details on the construction of these structures, see chapter 1, 
‘Graphics Primitives,” and chapter 2, “‘Layers.”’ 


The graphics animation routines described in this chapter create additional material that is 
linked into the View structure. This material consists of additional instructions for color 


changes and dynamic reassignment of the hardware resources that create the display animation 
effects you specify. | 


TYPES OF ANIMATION 


Using the Amiga system tools, you can perform two different kinds of image animation: sprite 
animation and playfield animation. 
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Sprite Animation 


Sprites are hardware objects that you create and move independently of the playfield display. 
Sprites are always 16 low-resolution pixels wide and are as high as you specify. To move 
sprites, you must define where they are on the screen. The built-in priority circuitry determines 
how the sprite appears on the screen relative to the playfield elements or to other sprites. 


You can manipulate sprites directly through a simple sprite set of routines or by using the 
graphics kernel VSprite routines. 


Playfield Animation 


Sprites are normally moved against a background. This background area is called the playfield. 
You may treat the playfield area as a single background or separate it into two separately con- 
trollable sections, using dual-playfield mode. See chapter 1, ‘‘Graphics Primitives,” for details 
on how to create and control playfields. 


In playfield animation, sections of the playfield are modified. You draw, erase, and redraw 
objects into the playfield, creating an animation effect. To move the data quickly and 
efficiently, the system uses one of the specialized built-in hardware devices, the blitter. The sys- 
tem uses the blitter to move the playfield objects, while it saves and restores the background. 
The objects controlled by the blitter are called Bobs, for ‘‘blitter objects.”’ 


Playfield animation is somewhat more complicated than VSprite animation from the point of 
view of system design, but not much more complicated for you as the user of the animation rou- 
tines. The hardware displays the VSprites over the playfield automatically, and the priority 
overlay circuitry assures that they will be displayed in the correct order. If you are animating 
multiple Bobs, you control their video priority by defining the sequence in which the system 
draws them. The last one drawn has the highest video priority in the sense that it appears to 
be in front of all other Bobs. 


A Bob 1s physically a part of the playfield. When the system displays a Bob, it must first 
save a copy of the playfield area into which the Bob will be drawn. Then the system can 
restore the playfield to its original condition when moving the Bob to a new location. Once the 
playfield areas have been saved, the system can draw the Bob. To move the Bob, the system 
must first restore the playfield area (thus erasing the object) before it saves the playfield at the 
new location and draws the Bob there. 


Bobs offer more flexibility and many more features than VSprites. Bob animation is less res- 
trictive but slower than VSprite animation. VSprites are superior to Bobs in speed of 
display, because VSprites are mostly hardware-driven and Bobs are part hardware and part 
software. Bobs, on the other hand, are superior to VSprites in that they offer almost all of 
the benefits of VSprites but suffer none of the limitations, such as size or number of colors. 
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Both are very powerful and useful. The requirements of your particular application determine 
the type of GEL to use. 


THE GELS SYSTEM 


The acronym GEL describes all of the graphic elements, or ‘“‘objects,’’ supplied by the Amiga 
ROM kernel. Both VSprites and Bobs are GELS, as are the more advanced animation ele- 
ments known as AnimComps and AnimObs. 


Initializing the GEL System 


To initialize the graphics element animation system, you provide the system with the addresses 
of two data structures. The system uses these data structures to keep track of the GELS that 
you will later define. To perform this initialization, you call the system routine InitGels(), 
which takes the form: 


InitGels( head, tail, Ginfo ); 
where 


head 
is a pointer to the VSprite structure to be used as the GEL list head 


tail 
is a pointer to the VSprite structure to be used as the GEL list tail 


Ginfo 


is a pointer to the GelsInfo structure to be initialized 


The graphics animation system uses two “dummy’’ VSprites as place holders in the list of 
GELS that you will construct. The dummy VSprites are used as the head and tail elements in 
the system list of GELS. You add graphics elements to or delete them from this list. 


The call to InitGels() forms a linked list of GELS that is empty except for these two dummy 
elements. When the system initializes the list with the dummy VSprite, it automatically gives 
the VSprite at the head the maximum possible negative y and x positions and the VSprite at 
the tail the maximum possible positive y and x positions. This assures that the two dummy ele- 
ments are always the outermost elements of the list. 


The y,x values are coordinates that relate to the physical position of the GEL within the draw- 
ing area. The system uses the y,x values as the basis for the placement (and later sorting) of 


the GELS in the list. 
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When you add a GEL to the list of graphics elements, the system links that GEL into the list 
shown above. Then the system adds any new element to the list immediately ahead of the first 
GEL whose y,x value is greater than or equal to that of the new GEL being added. 


Types of GELS 


Figure 3-1 shows how you can view the components of GELS as inter-related layers of graphics 
elements. 


Bob Bob Bob Bob 


Figure 3-1: Shells of Gels 





The types of GELS are listed below: 

o Simple (hardware) sprites 

o VSprites 

o Bobs 

o AnimComps 

o AnimObs 
VSprites and Bobs are the primary software-controlled animation objects. They are part of 
an integrated animation system. The simple sprites, on the other hand, are separate from the 


animation system. It is up to you to decide which type of sprite to use. The next sections 
describe all of these animation components. 
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Simple (Hardware) Sprites 


The simple sprite is a special graphics element, related to the graphics animation system only in 
that it vies with the VSprites for the use of the same underlying hardware elements, the real 
hardware sprites. 


The Amiga hardware has the ability to handle up to eight sprite objects. Each sprite is pro- 
duced by one of the eight hardware sprite DMA channels. Each sprite is 16-bits wide and arbi- 
trarily tall. The Amiga software provides a choice about how you can use these hardware ele- 
ments. You can either allocate one or more hardware sprites for your exclusive use, or you can 
allow all sprites to be managed by the system software and assigned as virtual sprites by the 
system. Using virtual sprites, it can appear as though you have an unlimited set of sprites with 
which to work. If you need only a few sprites, however, you may wish to use the less complex 
routines shown in the section called ‘Using Simple Sprites.”’ 


VSprites 


The virtual sprite is the most elemental component. It contains a little more information than 
is needed to define a hardware sprite. The system temporarily assigns each VSprite to a 
hardware sprite, as needed. The information in the VSprite structure allows the system to 
maintain the more general GEL functions, such as collision detection and double-buffering. 
After a sprite DMA channel has displayed the last line of a sprite, the system can reuse the 
channel to display a different image lower on the screen. The system software takes advantage 
of this reusability to dynamically assign hardware sprites to carry VSprite images. 


The VSprite is a data structure closely related to hardware sprites. The VSprite structure 
contains the following information: 


o Size 

o Image display data 
o Screen coordinates 
o Collision descriptors 


o A pointer to color information 
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Bobs 


The Bob is the next outermost level of the GEL system. It is like an expanded hardware sprite 
done in software. It uses the same information defined in a VSprite, but adds other data that 
further defines this type of object. Bobs and VSprites differ in that the system draws Bobs 
into the playfield using the blitter, while it assigns VSprites to hardware sprites. 
A Bob structure contains the following information: 

o A pointer to a VSprite 


o Priority descriptors 


o Variables and pointers that define how and where to save the background 
AnimComps 


The AnimComp (for “animation component”’) is a data structure that extends the definition of 
a Bob. It allows the system to include the Bob as part of a total animation object. An 
AnimComp expands on the Bob data. AnimComps include the following: 

o A pointer to this AnimComp’s Bob 


o Links that define the sequence of animation drawings 


o Information that describes the screen coordinates of the AnimComp with respect to 
the position of the AnimOb, described below 


o Timing information for sequencing this AnimComp as part of the list of animation 
drawings 


o A pointer to a user routine to execute in conjunction with this AnimComp 


AnimObs 


The AnimOb (for “animation object”’) is the primary animation object. It is a pseudo-object 
whose primary purpose is to link one or more AnimComps into a single overall object. As the 
AnimOb moves, so move its AnimComps. When the Bobs move with their AnimComps, 


the system sets the screen coordinates in the WSprite accordingly. AnimObs include the fol- 
lowing: 
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A pointer to this AnimOb’s first AnimComp 
Links to previous or succeeding AnimObs 


Information that describes the position of this AnimOb on the screen, as well as its 
velocity and acceleration 


Information for double-buffering this AnimOb, if desired 


A pointer to a user routine to execute in conjunction with this AnimOb 


Using Simple (Hardware) Sprites 


To use simple sprites, define their data structures and use the following routines: 


O 


ON_SPRITE — a system macro to turn on sprite DMA 
OFF_SPRITE — a system macro to turn off sprite DMA 


GetSprite() — attempts to allocate a sprite from the virtual sprite machine for your 
exclusive use 


ChangeSprite() — modifies the sprite’s appearance 
MoveSprite() — changes the sprite’s position 


FreeSprite() — returns the sprite to the virtual sprite machine 


These routines are described in detail in the following sections. 


To use these simple sprite routines or the VSprite routines, you must include the SPRITE flag 
in the data structure for OpenScreen(). If you are not using Intuition, this flag must be 
specified in the View and ViewPort data structures before MakeView() is called. 


CONTROLLING SPRITE DMA 


You can use the graphics macros ON_SPRITE and OFF_SPRITE to control sprite DMA. 
OFF_SPRITE prevents the system from displaying any sprites, whether hardware or VSprite. 
ON_SPRITE restores the sprite data access and display. Note that the Intuition cursor 1s a 
sprite. Thus, if you use OFF_SPRITE, you make Intuition’s cursor invisible as well. 
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ACCESSING A HARDWARE SPRITE 


You use GetSprite() to gain access to a new hardware sprite. You use a call such as 


status = GetSprite( sprite, number ) 


GetSprite() allocates a hardware sprite for your exclusive use. The virtual sprite allocator can 
no longer assign this sprite. Note that if you steal one sprite, you are effectively stealing two. 
The sprite pairs 0/1, 2/3, 4/5, and 6/7 share the same color registers. If you are stealing a 
hardware sprite, you steal its color registers as well. So you might as well ask for the other 
sprite in the pair. Table 3-1 shows the color registers assigned to each sprite pair. 


Table 3-1: Sprite Color Registers 


Color 
Registers Sprite 


16-19 0 or 1 
20-23 2or3 
24-27 4oro 
28-31 6 or 7 


You are not granted exclusive use of the color registers. If the ViewPort is 5 bit-planes deep, 
all 32 of the system color registers will still be used by the playfield display hardware. 


Note, however, that registers 16, 20, 24, and 28 always generate the “transparent” color when 
selected by a sprite, regardless of which color is actually in them. Their true color will be used 


only if they are selected by a playfield. For further information, see the Amiga Hardware Refer- 
ence Manual. 


Also note that sprites and sprite colors are bound to the ViewPort in that you can reload the 
colors between ViewPorts. In other words, if a user in a ViewPort located in the top part of 
the screen allocates sprite 0 and a user in the a ViewPort at the bottom of the screen allocates 
sprite 1, these two sprites will not necessarily have the same color set, as the two ViewPorts 


can have totally independent sets of colors. 
The inputs to the GetSprite() routine are: 


sprite A pointer containing the address of a data structure called SimpleSprite 


number The number (0-7) of the hardware sprite you wish to reserve. If number is -1, 
the system gets any sprite. 
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A value of 0-7 is returned in ‘“‘status’’ if your request was granted, specifying which sprite you 
have allocated. A value of -1 means that this sprite is already allocated. 


The structure for a simple sprite is shown below: 


struct SimpleSprite { 


/* pointer to definition data of the hardware sprite to be displayed */ 
UWORD *posctldata; 


UWORD height; /* height of this simple sprite in rows */ 
UWORD x,y; /* current position */ 


/* number (0-7) of hardware sprite associated with this simple sprite * / 
UWORD nun; 


} 


This data structure is found in the graphics/sprite.h file in the appendixes to this manual. 


CHANGING THE APPEARANCE OF A SIMPLE SPRITE 


The ChangeSprite() routine changes the appearance of a reserved sprite. It is called by the 
following sequence: 


ChangeSprite( vp, s, newdata ) 


ChangeSprite() substitutes a new data content for that currently used to display a reserved 
hardware sprite. 


The inputs to this routine are: 


vp A pointer to the ViewPort for this sprite or 0 if this sprite is relative only 
to the current View 


s A pointer to a SimpleSprite structure 
newdata A pointer to a data structure containing the new data to be used 


The structure for the new data is shown below: 
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struct userspritedata 


{ 


/* position and control information for this sprite */ 
UWORD posct][2]; 
/* two words per line of sprite height, first of the two 
* words contains msbit for color selection, second word 
* contains Isbit (colors 0,1,2,3 from allowable color 
* register selection set). Color ’0’ for any sprite 
* pixel makes it transparent. 
x 
/ 


UWORD sprdata[2][height]; /* actual sprite image */ 


/* initialize to 0, O for unattached simple spites * / 


UWORD reserved [2]; 
}3 


MOVING A SIMPLE SPRITE 


MoveSprite() repositions a reserved hardware sprite. It is called as follows: 


MoveSprite( vp, sprite, x, y ) 


After you call this routine, the reserved sprite is moved to a new position relative to the upper 
left corner of the ViewPort. 


The inputs to MoveSprite() are as follows: 


vp A pointer to the ViewPort with which this sprite interacts or 0 if this 
sprite’s position is relative only to the current View 


sprite A pointer to a SimpleSprite structure 


x, y Pixel position to which a sprite is to be moved. If the sprite is being 
moved over a high-resolution display, the system can move the sprite only 
in two-pixel increments. In low-resolution mode, single-pixel increments in 
the x direction are acceptable. For an interlaced mode display, the y direc- 
tion motions are in two line increments. The same image of the sprite is 
placed into both even and odd fields of the interlaced display. 


The upper left corner of the ViewPort area has coordinates (0,0). The motion of the sprite is 
relative to this position. 
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The following example demonstrates how you move a simple sprite. 


/* This program creates and displays a 320-by-200 by 2-bit-plane 
* single-playfield display and adds one simple sprite to it. 


oF 


#include ”exec/types.h” 
#include ” graphics/gfx.h” 
#include ”hardware/dmabits.h” 
#include ”hardware/custom.h” 
#include ”hardware/blit.h” 
#include ” graphics/gfxmacros.h” 
#include ” graphics/copper.h” 
#include ” graphics/view.h” 
#include ” graphics/gels.h” 
#include ” graphics/regions.h” 
#include ” graphics/clip.h” 
#include ” exec/exec.h” 
#include ” graphics/text.h” 
#include ” graphics/gfxbase.h” 
#include ” graphics/sprite.h” 


#define DEPTH 2 

#:define WIDTH 320 

#-define HEIGHT 200 

#-define NOT_ENOUGH_MEMORY -1000 


/* construct a simple display */ 


struct View view; 
struct ViewPort viewport; 


/* pointer to ColorMap structure, dynamically allocated */ 
struct ColorMap *cm; 


struct RasInfo rasinfo; 
struct BitMap bitmap; 


SHORT xmove, ymove; 


extern struct ColorMap *GetColorMap(); 
struct GfxBase *GfxBase; 


/* save pointer to old View so can restore */ 
struct View *oldview; 
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USHORT colortable|| = { 
/* black, red, green, blue */ 
0x000, Oxf00, OxOf0, Ox00f, 
0,0,0,0, 
0,0,0,0,0,0,0,0, 
0,0,0,0,0,0,0,0, /* sprites from here up */ 
0,0,0,0,0,0,0,0 


}; 


/* where to draw boxes */ 
SHORT boxoffsets|] = { 
802, 2010, 3218 

bi 


UWORD <xcolorpalette; 
struct SimpleSprite sprite; 


/* Last entry is ” position control” for the next reuse of the hardware sprite. 
* Simple sprite machine supports only one use of a hardware sprite per video 
* frame. Any combination of binary bits from word 1 and word 2 per line 
* establishes the color for a pixel on that line. Any nonzero pixels in lines 
* 1-3 are color ”1” of the sprite, lines 4-6 are color ”2”, lines 7-9 are color ”3”. 
* 
/ 
UWORD sprite_data| | = { 
0,0, /* position control */ 
OxOfc3, Ox0000, /* image data line 1 */ 
Ox3ff3, Ox0000, /* image data line 2 */ 
0x30c3, 0x0000, /* image data line 3 */ 
0x0000, Ox3c03, /* image data line 4 */ 
Ox0000, Ox3fc3, /* image data line 5 */ 
0x0000, 0x03c3, /* image data line 6 */ 
Oxc033, Oxc033, /* image data line 7 */ 
OxffcO, OxffcO,  /* image data line 8 */ 
Ox3f03, Ox3f03, /* image data line 9 */ 


/* NOTE this last line specifies unattached, simple sprites */ 
0, 0 /* next sprite field */ 


yi 


FECES ACOSO ICICI A a EI 
* FOLLOWING IS FOR INFORMATION ONLY.... the simple-sprite machine directly 
* sets these bits; the user has no need to change any of them. Use the 


* functions ChangeSprite() and MoveSprite() to have an effect on the sprite. 
* 
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position control: 


firsts UWORD: 
bits 15-8, start vertical value, lowest 8 bits of this value 
contained here. 
bits 7-0, start horizontal value, highest 8 bits of this value 
contained here. 


*k 
a 
* 
x 
* 
*k 
* 
* 
* second UWORD: 

* bits 15-8, end (stopping) vertical value, lowest 8 bits of this 

x value contained here. 

* bit 7 = Attach-bit (used for attaching sprites to get additional 
* colors (15 instead of 3, supported by the hardware but 

* NOT supported by the simple sprite machine). 

* bits 6-4 (unused) 

* bit 2 start vertical value; bit 8 of that value. 

x bit 2 end vertical value; bit 8 of that value. 

* bit 2 start horizontal value; bit O of that value. 

* 


FORO Ooo oo or ioiok ia iaiac doi doa dai iak dak ak ik kak kak a ak ak a akeak ack / 


main() 

{ 
LONG i; 
SHORT j,k,n; 


SHORT spgot; 
UBYTE *displaymem; 


GfxBase = (struct GfxBase *)OpenLibrary( ”graphics.library” , 0 ); 
if( GfxBase =— NULL ) exit(100); 


/* save current view to restore later */ 
oldview = GfxBase- > ActiView; 


/* example steals screen from Intuition if started from WBench */ 


InitView( S&view ); /* initialize View */ 
InitVPort( &viewport ); /* init ViewPort */ 
view.ViewPort = &viewport; /* link View into ViewPort */ 


/* init bit map (for RasInfo and RastPort) */ 
InitBitMap( &bitmap, DEPTH, WIDTH, HEIGHT ); 


/* init RasInfo */ 
rasinfo.BitMap = &bitmap; 
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rasinfo.RxOffset = 0: 
rasinfo.RyOffset = 0; 
rasinfo.Next = NULL; 


/* now specify critical characteristics * / 
viewport. DWidth = WIDTH; 
viewport.DHeight = HEIGHT; 


viewport.RasInfo = &rasinfo; 


/* initialize the color map. It has 32 entries. Sprites take up 
*the top 16 and we want to specify some sprite colors */ 
cm = GetColorMap( 32 ); 


/* no memory for color map */ 
if(em —= NULL) { 
FreeMemory(); 
exit( 100 ); 


} 


colorpalette = (UWORD *)cm->ColorTable; 
for(i=0; i<32; i++) { 

*colorpalette++ = colortable{i]; 
} 


/* copy my colors into this ViewPort structure */ 
viewport.ColorMap = cm; 


/* addition for simple sprite: */ 
vp.Modes = SPRITES; 


/* allocate space for bitmap */ 

for(i=0; i<DEPTH; i++) { 
bitmap.Planes|i] = (PLANEPTR) AllocRaster( WIDTH, HEIGHT ); 
if( bitmap.Planes|i] =— NULL ) exit( NOT_ENOUGH_MEMORY ); 


/* clear the display area */ 
BltClear( bitmap.Planes[i], RASSIZE(WIDTH,HEIGHT), 1 ); 


} 


/* construct Copper instr (prelim) list */ 
MakeVPort( &view, &viewport ); 


/* merge prelim lists into a real Copper list in the view structure. */ 


MrgCop( &view ); 
LoadView( &view ); 
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/* now fill some boxes so that user can see something */ 
/* always draw into both planes to assure true colors */ 
for(n=1; n<4; n++) /* three boxes */ 
{ 
for(k—=0; k<2; k++) 
{ 
/* boxes will be in red, green and blue */ 
displaymem = bitmap.Planes|k] + boxoffsets|n-1]; 
DrawF illedBox( n, k, displaymem ); 


j 


| aaNet TailastaTailastilasiiTaitosadTaateTaitedailasediotadtastataitntadtasodtadtotaitoiaitotoilataitetaiiatasiaied 


* Now we are ready to play with the sprites! 
FSCO SIGS SSSI Rk / 


/* Get the next available sprite. We should do an error 
* check, if returns -1, then no sprites are available 
+ 


spgot = GetSprite( &sprite, -1 ); 


sprite.x = 0; /* initialize position and size info */ 
sprite.y = 0; /* matches that shown in sprite_data */ 
sprite.height = 9; /* so that system knows layout of data later */ 


/* now put some colors into this sprite’s color registers 

* to custom-control the colors this particular sprite will display. 

* NOTE: sprite pairs share color registers; 1.e., sprites 0 and 1, 

* 2 and 3, 4 and 5, 6 and 7 as pairs share the same sets of color 

* registers (see the Amiga Hardware Reference manual for details). 
* The code following figures out which sprite the system gave us, 
** and sets that sprite’s color registers to the correct value 

+] 

k = ((spgot & Ox06)*2) + 16; 


/* convert sprite number into the base number for its color reg set */ 
/* value at k treated as transparent */ 

SetRGB4( &viewport, k+1, 12, 3, 8 ); 

SetRGB4( &viewport, k+2, 13, 13, 13 ); 

SetRGB4( &viewport, k+3, 4, 4, 15 ); 


/* top of sprite is red, middle is white, bottom is blueish */ 
ChangeSprite( &viewport,&sprite,sprite_data): 


MoveSprite(0, &sprite,30,0); 
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} 


xmove — 1; ymove = |]; 
fori n = 0;n < 4,n++) { 
i=0; 
while( i++ < 185 ) { 
MoveSprite( 0, &sprite, sprite. x + xmove, sprite.y + ymove ); 


/* slow it down to one move per video frame */ 


WaitTOF(); 
} 
ymove = -ymove; 
xmove = -xmove; 


} 


/* free this sprite so others can use it also */ 
FreeSprite( spgot ); 


/* restore the system to its original state */ 
Load View( oldview ); 

FreeMemory(); 

CloseLibrary( GfxBase ); 


/* end of main() */ 


/* return user and system-allocated memory to sys manager */ 
FreeMemory() 


} 


LONG i; 


/* free drawing area */ 
for( i=0; i<DEPTH; i++ ) { 
if( bitmap.Planes|i] !== NULL ) { 
FreeRaster( bitmap.Planes|i], WIDTH, HEIGHT ); 
} 
} 


/* free the color map created by GetColorMap() */ 
if( cm !== NULL ) FreeColorMap( cm ); 


/* free dynamically created structures */ 
FreeVPortCopLists( &viewport ); 
FreeCprList( view.LOFCprList ); 

return( 0 ); 


DrawF illedBox( fillcolor, plane, displaymem ) 
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SHORT fillcolor,plane; 
UBYTE *displaymem; 


UBYTE value; 
LONG ]; 


for(j=0; j<100; j++) { 
if((fillcolor & (1 << plane)) != 0) { 


value = Oxf; 
} else { 


value = 0; 


for(i=0; i<20; i++) { 
*displaymem++ = value; 
} 


displaymem += (bitmap.BytesPerRow - 20); 


} 


return(0); 


RELINQUISHING A SIMPLE SPRITE 


The FreeSprite() routine returns an allocated sprite to the virtual sprite machine. The virtual 
sprite machine can now reuse this sprite to allocate virtual sprites. The syntax of this routine is 


FreeSprite( num ) 
where num is the number (0-7) of the sprite you want to return. 
Note: You must free sprites after you have allocated them using GetSprite(). If you do not 


free them and your task ends, the system will have no way of reallocating those sprites until the 
system 1s rebooted. 


Using VSprites 


This section tells how to define a VSprite. It describes how to: 


o Specify the size of the VSprite object 
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o Select its colors 
o Form its image 
o Specify its position within the drawing area 
o Add it to the list of GELS 
o Control it after you add it to the list 
The system software also provides a way to detect collisions between individual VSprites and 


other on-screen objects. Collision detection applies to both VSprites and to Bobs. It appears 
as a separate topic under “Topics Common to Both VSprites and Bobs.”’ 


SPECIFYING THE SIZE OF A VSPRITE 


The first step in defining a VSprite is telling its dimensions to the system. A VSprite is 
always 16 pixels wide and may be any number of lines high. Each pixel is the same size as a 
pixel in low-resolution mode (320 pixels across a horizontal line) of the graphics display. To 


specify how many lines make up the VSprite image, you use the VSprite structure Height 
variable. 


If your VSprite is 12 lines high and the name of your VSprite structure is myVSprite, then 
you can set the height value with.the following statement: 


my VSprite.Height = 12; 


Each line of a VSprite requires two data words to specify the color content of each pixel. This 
means that the data area containing the VSprite image is 12 x 2, or 24, words long. 


See the next section for details on how bits of these data words select the color of the VSprite 
pixels. 


SPECIFYING THE COLORS OF A VSPRITE 


Because VSprites are so closely related to the hardware sprites, the choice of colors for 
VSprites is limited in the same way. Specifically, each pixel of a VSprite can be any one of 
three different colors or it may be transparent. However, the system software provides a great 
deal of versatility in the choice of colors for the virtual sprites. Each virtual sprite may have its 
own set of three unique colors. 
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When the system assigns a hardware sprite to carry the VSprite’s image, it assigns that 
VSprite’s color set to the hardware sprite that will produce that image. To define which set of 
three colors to use for this VSprite, you initialize the VSprite structure pointer named 
SprColors. SprColors points to the first data item of three sequentially-stored 16-bit values. 
The system then jams these values into the selected hardware sprite’s color registers when it is 
being used to display this VSprite. 


Every time you direct the system to redraw the VSprites, the GEL system reevaluates the 
current on-screen position of each VSprite and decides which hardware sprite will carry this 
VSprite’s image for this rendering. It creates a customized Copper instruction sequence includ- 
ing both the repositioning of hardware sprites and the reloading of sprite color registers for vari- 
ous screen positions. Thus, during a move sequence, a VSprite may be represented by one or 


many different real hardware sprites, depending on its current position relative to other 
VSprites. 


For example, if your set of colors is defined by the statement: 


WORD spriteColors = { 0x00F, O0xOFO, OxF00 }; 


and if your VSprite is named myVSprite, to set the VSprite colors you would use the follow- 
ing statement: 


my VSprite.SprColors = &spriteColors; 


How you specify the VSprite colors may affect how many VSprites you can show on the 
screen at any one time. For further information, see ““How VSprites are Assigned.”’ 


SPECIFYING THE SHAPE OF A VSPRITE 


To define the appearance of a VSprite, initialize the VSprite structure pointer called 
ImageData to point to the first word of the image data. A VSprite image is defined exactly 


as the image of a real hardware sprite. It takes two sequential 16-bit data words to define each 
line of a VSprite. 


To select colors for the pixels of a VSprite, examine the combination of the data bits in 
corresponding locations in each of the two data words that define each line. The first of each 
pair of data words supplies the low-order bit of the color selector for that pixel; the second word 


of the pair supplies the high-order bit. 


For example: 
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mem 0101111111111111 
mem+1 0011111111111111 


Reading from left to right, the combinations of these two sequential memory data words form 
the binary values of 00, 01, 10, 11, and soon. These binary values select colors as follows. 


00 - selects VSprite color of “transparent”’ 

O1 - selects the first of three VSprite colors you have defined 
10 - selects the second VSprite color 

11 - selects the third VSprite color 


In those areas where the combination of bits yields a value of 00, the VSprite is transparent. 
Any object whose priority is lower than that of the VSprite will show through in transparent 
sections of the VSprite. Thus, you might form a full three-color image, with some transparent 
areas, from a data set like the following sample: 


VSprite Data 


mem 1111111111111111 Defines top line - 
mem +1  1111111111111111 contains only color 3 


mem+2 0011111111111100 Defines second line - 
mem +3  0011000000001100 contains colors 1 and 3 and 
some transparency 
mem +4 0000110000110000 Defines third line - 
mem +5 0000111111110000 contains colors 2 and 3 
and some transparency 
mem +6 0000001001000000 Defines fourth line - 
mem + 7 90000001111000000 contains colors 2 and 3 
and some transparency 


mem +8  Q000000110000000 Defines last line - 
mem +9 0000000110000000 = contains color 3 and 
some transparency 


The VSprite Height for this sample image 1s 5. 


SprColors must point to the set of three colors that are to be used to display this VSprite, 
and ImageData must point to the location (“mem” in the example) that contains the first 
word of the VSprite definition. 
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SPECIFYING VSPRITE POSITION 


To control the position of a VSprite, you use the y and x variables within the VSprite struc- 
ture. You specify the position of the upper left corner of a VSprite relative to the upper left 
corner of the drawing area where you wish the VSprite to appear. Assign a value of 0,0 for y,x 
to make the VSprite appear with its upper left corner against the upper left corner of the 


drawing area. You can use values of y and x to move the VSprite entirely off the screen, if you 
wish. 


You resolve the vertical positioning for VSprites in terms of the non-interlaced mode of the 
display. When you position a VSprite so that its y value is within the visible area of the 


screen, you can select any one of 200 possible positions down the screen at which its topmost 
edge can be placed. 


You resolve the horizontal positioning for VSprites in terms of the low-resolution mode of the 
screen display. When you position a VSprite so that its x value is within the visible area of 
the screen, you can select any one of 320 possible positions across the screen at which its left- 
most edge can be placed. Note that if you are using VSprites under Intuition and within a 
screen, they will be positioned relative to the upper left-hand corner of the screen. 


USING VSPRITE FLAGS 


Now that you have defined the VSprite’s size, colors, shape, and position, you may want to 
know where to add information to the data structures or where to check about the progress of 


the system routines. The following sections describe the functions of the VSprite flags, the 
variables that let you do some of these activities. 


The VSprite data structure contains a variable named Flags that has information about its 
data and about the progress of the system routines. The following sections describe the uses of 
the VSPRITE, VSOVERFLOW, and GELGONE flags. You can use these flags to perform these 
tasks: 


VSPRITE Indicate whether the system should treat the structure as a VSprite or 
part of a Bob. 


VSOVERFLOW Check on the VSprites the system cannot display. (This is a read-only 


system variable.) 


GELGONE Find out if the system has moved a GEL outside the clipping region of 
the drawing area. (This is a read-only system variable.) 
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VSPRITE Flag 


To tell the GEL routines to treat this VSprite structure as a VSprite instead of a Bob, set the 
VSPRITE flag to 1. This affects the interpretation of the data layout and the use of various 
system variables. If you set the VSPRITE flag bit to zero, the GEL routines treat this VSprite 
structure as though it defined a Bob instead of a VSprite. 


Note: Under Intuition, VSprites work only in screens, not in windows. Bobs work in both 
screens and in windows. Thus, if you wish to use VSprites and Bobs together, you can only 
do so by writing directly to the RastPort of a screen. 


VSOVERFLOW Flag 


If you have currently defined more VSprites at the same horizontal line than the system can 
possibly assign to the real hardware sprites, then the VSprites that the system cannot display 
have their VSOVERFLOW flag set. This means that it is possible that one or more VSprites 
will not appear on the display for this pass of producing the GELS. 


GELGONE Flag 


When the GELGONE flag is set to 1, you know that the system has moved a GEL (VSprite or 
a Bob) entirely outside of the clipping region of the drawing area. You can assume that the 
system will fully or at least partially draw any objects within the clipping region. Because the 
system will not draw this object that is outside the clipping area, you may wish to use 
RemVSprite() to delete the VSprite from the GEL list in order to speed up processing of the 


rest of the list. Of course, VSprites that you remove from the list are no longer managed or 
checked by the system. 


ADDING A VSPRITE 


To control VSprites, you first describe them using the VSprite structure variables mentioned 
above. Next you tell the system (by adding the VSprites to the GEL list) which VSprites to 
handle. This section tells you how to add a VSprite to the GEL list. 


To add a VSprite to the system GEL list, call the system routine AddVSprite(), and specify 
the address of the VSprite structure that controls this WSprite as well as the RastPort with 
which it is associated. 
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A typical system call for this purpose follows: 


struct VSprite my VSprite; 
AddVSprite( &myVSprite, &rastport ); 


REMOVING A VSPRITE 


To remove a VSprite from the list of controlled objects, use the system routine 
RemVSprite(). This function takes the following form: 


RemVSprite( VS ); 


where VS is a pointer to the VSprite structure to be removed from the GEL list 


GETTING THE VSPRITE LIST IN ORDER 


When the system has displayed the last line of a VSprite, it reassigns the hardware sprite to 
another VSprite located at a lower position, farther left on the screen. The system allocates 
hardware sprites in the order in which it encounters the VSprites in the list. Therefore, you 


must sort the list of VSprites before the system can assign the use of the hardware sprites 
correctly. 


When you first enter VSprites into the list using AddVSprite(), the system uses the y,x coor- 


dinates to place the VSprites into the correct position in the list. If you change the y,x coordi- 


nates after they are in the list, you must reorder the list before the system can use it to produce 
the display. 


You use the routine SortGList() (for “sort the GEL list”) to get them in the correct order 


before asking the system to display them. This sorting step is essential! You call this function 
as follows: 


SortGList( RPort ); 
where RPort is a pointer to the RastPort structure containing the GelsInfo 


Note that there may be a GEL list in more than one RastPort. You must sort all of them. 
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DISPLAYING THE VSPRITES 


The next few sections explain how to display the VSprites. You use the following system 
routines: 


o ON_DISPLAY — to turn on the playfield display 

o ON_SPRITE — to turn on the VSprites display 

o DrawGList() — to draw the elements into the current RastPort 
o MrgCop() — to install the VSprites into the display 

o LoadView() — to ask the system to display the new View 


o WaitTOF() — to synchronize the routines with the display 


Turning on the Display 


Before you can view a display on the screen, you must enable the system direct memory access 
for both the hardware sprites and the playfield display. To enable the display of both playfield 
and VSprites, use the system macro calls: 


ON_DISPLAY; 
ON_SPRITE; 


Drawing the Graphics Elements 


The system routine called DrawGList() looks through the list of controlled GELS. It prepares 
necessary instructions and memory areas to display the data according to your requirements. 
You call this routine as follows: 


DrawGList( RPort, VPort ); 
where 


RPort 
is a pointer to the RastPort 
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VPort 
is a pointer to the View 


Because the system links VSprites to a View, the use of a RastPort is not significant for 
them. However, you can use DrawGList() for Bobs as well as VSprites, so it is required that 


you pass the pointer to the RastPort to the routine. DrawGList() actually draws Bobs into 
that RastPort when you execute the instructions. 


Once DrawGList() has prepared the necessary instructions and memory areas to display the 
data, you will need to install the VSprites into the display with MrgCop(). 


Merging VSprite Instructions 


Recall that the call to DrawGList() did not actually draw the VSprites. It simply provided a 
new set of instructions that the system uses to assign the VSprite images to real hardware 
sprites, based on their positions. The View structure already has a set of instructions that 
specifies how to construct the display area. It includes pointers to the set of VSprite instruc- 
tions that was made by the call to DrawGList(). To install the current VSprites into the 


display area, you call the routine MrgCop() to merge together all of the display-type instruc- 
tions in the View structure. You call this routine as follows: 


MrgCop( View ); 
where View is a pointer to the View structure whose Copper instructions are to be merged 


DrawGList() handles Bobs as wells as VSprites. Therefore, the call to DrawGList(), 


although it did not really draw the VSprite images yet, does draw the Bobs into the selected 
RastPort. 


Loading the New View 


Now that the display instructions include the definition of the VSprites, you can ask the sys- 


tem to prepare to display this newly configured View. You do this with the following system 
routine: 


Load View( view ); 
where view is a pointer to the View that contains the pointer to the Copper instruction list 
The Copper instruction lists are double-buffered, so this instruction does not actually take effect 


until the next display field occurs. This avoids the possibility of some routine trying to update 
the Copper instruction list while the Copper is trying to use it to create the display. 
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Synchronizing with the Display 


To synchronize your routines with the display, you use a call to the system routine 
WaitTOF(). Although your routines may possibly be capable of generating more than 60 com- 
plete display fields per second, the system itself is limited to 60 displays per second. Therefore, 
after generating a complete display, you may wish to wait until that display is ready to be 
shown on the screen before starting to generate the next one. WaitTOF() holds your task 
until the vertical-blanking interval (blank area at the top of the screen) has begun. At that 
time, the system has retrieved the current Copper instruction list and is ready to allow genera- 
tion of a new list. 


The call to the vertical-blanking synchronization routine takes the following form: 


WaitTOF(); 
Now that you have learned how to add and display VSprites, you may want want to change 


some of their characteristics, as shown in the following section. 


Changing VSprites 


Once the VSprite has been added to the GEL list and is in the display, you can change some of 
its characteristics with the following operations: 


o Pointing to a new VSprite image (change the ImageData pointer) 
o Pointing to a new VSprite color set (change the SprColors pointer) 


o Defining a new VSprite position (change the y,x values) 


VSPRITE OPERATIONS SUMMARY 


This section provides a summary of the VSprite operations in their proper sequence: 
o Define a View structure that you can later merge with the VSprite instructions. 
o Initialize the GEL system (call InitGels()). This only needs to be done once. 
o Define the VSprite: 


- Define height. 


Animation 129 


- Define on-screen position. 
- Define where to find ImageData data. 
- Define where to find SprColors to use. 
- Define VSprite structure flags to show that this is a VSprite. 
o Add the VSprite to the GEL list. 
o Change the VSprite appearance by doing the following: 
- Changing the pointer to ImageData. 
- Changing its height. 
o Change the VSprite colors by changing the pointer to SprColors. 
o Move the VSprite by defining a new y,x position. 
o Display the VSprite with this sequence of routines: 
- ON_DISPLAY; 
- ON_SPRITE; 
- SortGList() 
- DrawGList() 
- MrgCop() 
- LoadView() 
Once you have mastered the basics of handling VSprites, you may want to study the next two 


sections to find out how to reserve hardware sprites for use outside the VSprite system and 
how to assign the VSprites. 
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VSPRITE ADVANCED TOPICS 


This section describes advanced topics pertaining to VSprites. It contains details about reserv- 
ing hardware sprites for use outside of the VSprite system, information about how VSprites 
are assigned, and more information about VSprite colors. 


Reserving Hardware Sprites 


To prevent the VSprite system from using specific hardware sprites, you can write into the 
variable named sprRsrvd in the GelsInfo structure. The pointer to the GelsInfo structure is 
contained in the RastPort structure. If the contents of this 8-bit value is zero, then all of the 
hardware sprites may be used by the VSprite system. If any of the bits is a 1, the sprite 
corresponding to that bit will not be utilized by VSprites. Note that this increases the likeli- 
hood of a VSprite VSOVERFLOW. See the next section, ‘‘How VSprites are Assigned,” for 
further details on this topic. 


Hardware sprites are reserved as shown below. 


This sprite is reserved: 76543210 


If this sprRsrvd bitisal: 76543210 


You normally assign hardware sprites in pairs, as suggested by the following example. Suppose 


you want to reserve sprites 0 and 1. Your program would typically include the following kinds 
of statements: 


struct RastPort myRastPort; /* the View structure is defined */ 


my RastPort- > GelsInfo->sprRsrvd = 0x03; /* reserve 0 and 1 */ 
If you reserve a hardware sprite for your own use, the system is unable to use that hardware 
sprite when it makes a VSprite assignment. In addition, because pairs of hardware sprites 


share color register sets, reserving one hardware sprite effectively eliminates two. 


If you are using the simple sprite system to allocate sprites, you can look in the GfxBase struc- 
ture to see which sprites are already in use. 


Note: If Intuition is running, sprite 0 is already reserved for use as the pointer. 
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The reserved sprite status is accessible as 


currentreserved = GfxBase->SpriteReserved 


The next section presents a few trouble-shooting techniques for VSprite assignment. 


How VSprites Are Assigned 


Each VSprite can display three possible colors plus transparent. To define colors for 
VSprites, you use the SprColors pointer. SprColors points to the first of three word quanti- 
ties, representing the three possible pixel colors for that virtual sprite. 


Although the VSprites are handled by the automatic routines, the system may run out of 
sprites. If you ask that the software display more than four VSprites on a single horizontal 
scan line, it is possible that one or more sprites may disappear until the conflict is resolved. 


Here is the reason that the VSprite routines might have problems, and some suggestions on 
how to avoid them. There are 8 real sprite DMA channels. Sprites 0 and 1 share color registers 


17-19; sprites 2 and 3 share registers 21-23; sprites 4 and 5 share registers 25-27; and sprites 6 
and 7 share registers 29-31. 


When the VSprite routines use the sorted list of WSprite elements, they build a Copper 
instruction list that decides when to reuse a sprite DMA channel. They also build a Copper 
instruction stream that stuffs the color register set for the sprite selected at that time on the 
screen to represent this VSprite image. 


This process consists of the following steps: 


1. Use real sprite O to represent the first virtual sprite. Load that virtual sprite’s colors 
into the three color registers for sprite 0 (registers 17, 18, 19). 


2. Now look at the rest of the virtual sprites the user wishes to display on this same hor- 
izontal line. 


3. If the VSprite color pointers are all different from the pointer found in the sprite 0 
pointer, it will not be possible to use the real sprite 1 DMA channel for display on this 
line because it shares the real sprite 0 colors. 


4. Conversely, if one of the other virtual sprites to appear on this line shares the same vir- 


tual color pointer, the VSprite routines can use sprite DMA channel 1 to represent 
that second virtual sprite. 
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5. The VSprite routines continue to map virtual sprites against the real sprites until 
either of the following events occurs: 


o All virtual sprites are assigned. 
o The system runs out of real sprites that it can use. 
The system will run out of real sprites to use if you ask the virtual sprite system to display 
more than four sprites having different pointers to their color table on the same horizontal line. 
During the time that there is a conflict, one or more of your virtual sprites will disappear. 
You can avoid these problems by taking the following precautions: 
o Minimize the number of VSprites you wish to appear on a single horizontal line. 
o If colors for some virtual sprites are the same, make sure that the pointer for each of 


the VSprite structures for these virtual sprites points to the same memory location, 
rather than to a duplicate set of colors elsewhere in memory. 


If You Do Not Specify VSprite Colors 


To pick the set of colors to use, you specify the pointer named SprColors. If you specify a 0 
value for SprColors, that VSprite does not generate a color-change instruction stream for the 
Copper when the system displays it. Instead, the VSprite appears drawn in the color set that 
is currently written into the color registers for the hardware sprite currently selected to display 
this VSprite. 


Table 3-2 shows how the hardware sprites use the color registers to select their possible range of 
colors: 


Table 3-2: Hardware Sprite Color Registers 


Hardware Sprite Color Registers 


O and 1 17 - 19 
2 and 3 21 - 23 
4 and 5 25 - 27 
6 and 7 29 - 31 


During one screen display, the system may use hardware sprite number 1 to display a VSprite. 
In this case, the VSprite selects its three available colors from color register numbers 17-19. 
On another screen display, the system may select hardware sprite number 7 to display the same 
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VSprite. In this case, the hardware sprite uses color registers 29-31. 


Therefore, if you make the SprColors pointer a 0, specifying that color does not matter, the 


system may display your VSprite in any one of a set of four different possible color groupings 
as indicated in the table above. 


How VSprite and Playfield Colors Interact 


The VSprites use system color registers 16 through 31 to hold the VSprite color selections. 
There are only 32 color registers in the system. The highest 16 color registers (16-31) are shared 
with the playfield color selections. If you are working in 32-color low-resolution mode, the sys- 
tem makes the first 16 color selections for the playfield pixels from color registers 0-15 and then 
makes the remaining color selections from color registers 16-31. 


If you are using the VSprite system and specifying the colors (using SprColors) for each 
VSprite, the contents of color registers 16-31 will change constantly as the video display beam 
progresses down the screen. The Copper instructions change the registers to display the correct 
set of colors for your VSprites depending on their positions. If you have any part of a 32-color 
playfield display drawn in any of the colors shown in table 3-2, those colors will appear to flicker 
and change as your VSprites move. 


This problem also affects 32-color Bobs because Bobs are actually drawn as part of the 
playfield display. Anything that affects the playfield affects the Bobs as well. 


You can avoid this flickering and changing of colors by taking the following precautions: 
o Use no more than 16 colors in the playfield display whenever you use VSprites; or 


o If you are using a 32-color playfield display, do not use any colors other than 0-15, 16, 
20, 24, and 28. The remaining color numbers are used by the VSprite system; or 


o Specify the VSprite SprColors pointer as a value of 0. This avoids changing the con- 
tents of any of the hardware sprite color registers, but may cause the VSprites to 


change colors depending on their positions relative to each other, as described in the 
previous section. 


The first two alternatives are the easiest to implement. 
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Using Bobs 


Because Bobs and VSprites are both graphics objects handled by the GEL system, they share 
many of the same data requirements. VSprites and Bobs differ primarily in that Bobs are 
drawn into the playfield using the blitter, while VSprites are assigned to hardware sprites. 


The following sections describe how to define a Bob, including how to specify its size, select its 
colors, form its image, and specify its on-screen position. 


Because a Bob is a more complex object than a VSprite, you must also define various other 
items, such as the color depth of the Bob, how to handle the drawing of the Bob, and certain 
other variables that the GEL system requires when Bobs are used. 


LINKING A BOB TO A VSPRITE STRUCTURE 


To fully define a Bob, you define two different structures: a VSprite structure and a Bob 
structure. The graphics animation system has been designed as a set of interrelated elements, 
each of which builds on the information provided by the underlying structure to create addi- 
tional versatility. The common elements—such as height, collision-handling information, posi- 
tion in the drawing area, and pointers to the data definition—are part of the VSprite struc- 
ture. The added features—such as drawing sequence, data about saving and restoring the 
background, and other features not common to VSprites—are part of the Bob structure 
instead. 


The VSprite and Bob structures must point to one another, so that the system knows where 


all of the appropriate variables are defined. For example, suppose your program defines two 
structures that are to define a Bob named ‘“‘myBob”’ as follows: 


struct Bob myBob; 
struct VSprite myVSprite; 


You must create a link between the two structures with a set of program statements such as: 


myBob.BobVSprite = &myVSprite; 
my VSprite.VSBob = &myBob; 


Now the system can go back and forth between the two structures to obtain the various ele- 
ments as needed to define the Bob. 
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SPECIFYING THE SIZE OF A BOB 


Whereas a VSprite was limited to 16 pixels of width, a Bob can be any size you wish to define. 
To specify the size of a Bob, you use not only the Height but also the Width variable. You 
specify these variables in a VSprite structure associated with the Bob. Specify the width as 
the number of 16-bit words it takes to fully contain the object. 


As an example, suppose the Bob is 24 pixels wide and 20 lines tall. You use statements such as 
the following to specify the size: 


my VSprite.Height = 20; /* 20 lines tall */ 
myVSprite.Width = 2; /* 2 words = 24 pixels wide, rounded 
* up to the next multiple of 16 pixels. */ 


Because Bobs are drawn into the playfield background, the pixels of the Bob are the same size 


as the background pixels. With hardware sprites, the pixels are of a fixed size (low-resolution 
pixels). 


SPECIFYING THE COLORS OF A BOB 


Because a Bob is drawn into the playfield area, it can have as many colors as the playfield area 
itself. Typically a five-bit-plane, low-resolution mode display allows you to select playfield pix- 
els (and therefore, Bob pixels) from any of 32 active colors out of a system palette of 4,096 
different color choices. The set of colors you select for the playfield area is the set of colors the 
system uses to display the Bobs. 


For Bobs, the system ignores the SprColors variable in the VSprite structure. You use the 
Depth variable in the VSprite structure to define how much data is provided to define the 
Bob. This variable also defines how many different colors you can choose for each of the pixels 


of a Bob. 


The Depth variable specifies how many bit-plane images the system must retrieve from the 
Bob image data area to make up the Bob. These are called bit-plane images as the system will 
write each image into a different bit-plane. The combination of bits in identical y,x positions in 
each bit-plane determines the color of the pixel at that position. 


For example, if you specify only one plane, then the bits of that image let you select only two 
different colors: one color for each bit that is a 0, a second color for each bit that is a1. Like- 
wise, if there are 5 images stored sequentially and you specify a depth of 5, each image contri- 
butes one bit for each position in the image to the color number selector, allowing up to 32 
different choices of color for each Bob pixel. 
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You specify depth using a statement such as the following: 


my VSprite.Depth = 5; /* allow 32 colors; requires that a 
* 5-bit-plane image be present in data area. */ 


SPECIFYING THE SHAPE OF A BOB 


The organization of a Bob in memory is different from that of a VSprite because of the way 
the system retrieves data to draw Bobs. To define a Bob, you must still initialize the 


ImageData pointer to point to the first word of the image definition; however, the layout of 
the data is different for Bobs than for VSprites. 


The sample image below shows the same image defined as a VSprite in the ‘‘Using VSprites”’ 
section above. The data, however, is stored in a way typical of a Bob. 


If a shape is 2 bits “deep” and is a triangular shape, you would lay it out in memory as follows: 


<first bit-plane data> 


mem 1111111111111111 
mem-+ 1  0011000000001100 
mem+2 0000111111110000 
mem +3  0000001111000000 
mem + 4 00000001 10000000 


<second bit-plane data> 


mem+o9 II111111111111111 
mem+6 0011111111111100 
mem +7 00001100001 10000 
mem+8 0000001111000000 
mem +9 00000001 10000000 


<<third bit-plane data> 
<<fourth bit-plane data> 


<<fifth bit-plane data> 


To state the width of the Bob image, you use 16-bit words. The Width value is the number of 
words that fully contain the image. For example, you store a 29-bit wide image in 32 bits (2 
data words of 16 bits each) for each line of its data. 
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You still specify the number of lines with the Height variable in the VSprite data structure. 
However, you treat Height somewhat differently for a Bob than for a VSprite. Specifically, 
for a VSprite, two adjacent data words that always occur together define the colors of each 
VSprite pixel. For a Bob, the Height variable defines how many adjacent data words it takes 
to define one complete bit-plane image. That is, for a Bob the number of adjacent data words 
in each bit-plane image definition is given by the following formula: Height x Width. 

The Depth variable defines how many adjacent (end-to-end) images there are in the data area 


to define the shape of the Bob. See the example at the end of the ““PlaneOnOff”’ section below. 


OTHER ITEMS INFLUENCING BOB COLORS 


Three other variables in the VSprite structure affect the color of Bob pixels: PlanePick, 
ImageShadow, and PlaneOnoff. 


PlanePick 


Assume that you have defined a playfield composed of five bit-planes. The variable PlanePick 
in the VSprite structure lets you specify which of the bit-planes are to be affected when the 


system draws the Bob. PlanePick binary values affect the bit-planes according to the follow- 
ing pattern: 


Draw Bob into this bit-planes 543210 
If this PlanePick bit is a 1: 543210 


For example, if PlanePick has a binary value of: 


00011 


then the system draws the first bit-plane image of the Bob into bit-plane 0 and the second 
image into bit-plane 1. 


Suppose that you still want to define an image of only 2 bit-planes, but wish to draw the Bob 
into bit-planes 1 and 4 instead of 0 and 1. Simply choose a PlanePick value of: 


10010 


This value means ‘“‘write first image into plane 1, second image into plane 4.” 
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ImageShadow 


The variable named ImageShadow is a pointer to a memory area that you have reserved for 
holding the shadow mask of a Bob. A shadow mask is the logical or combination of all 1-bits 
of a Bob image. There is a variable in the VSprite structure called CollMask (pointer to a 
collision mask, covered under “Topics Common to Both VSprites and Bobs’’) for which you 
reserve some memory space. The ImageShadow and CollMask pointers usually, but not 
necessarily, point to the same data. 


Figure 3-2 shows an example of a shadow mask with only the 1 bits. 


If this is the image in: Then its !mage Shadow is: 


Plane 1 Plane 2 
1711111111111 1711111111117 





Figure 3-2: An Image and Its ImageShadow 


The system uses the shadow mask along with the variable PlaneOnOff, discussed in the next 
section. Because ImageShadow in the Bob structure is a pointer to a data area containing 
the sprite shadow, you must provide space that the the system can use for this purpose. You 
must then initialize the pointer to the first location within the data area that you have set 
aside. You can calculate the minimum size of this area as follows: 


shadow size = Height * Width 


So, for example, an object 5 lines high by 32 bits wide (VSprite or Bob) requires a sprite sha- 
dow storage area of at least 5 x 2, or ten 16-bit locations. The example in the “PlaneOnOff”’ 
section below shows how to reserve the memory for the sprite shadow and how to tell the sys- 
tem where to find it. 
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PlaneOnOff 


The variable named PlaneOnOff tells the system what to do with the playfields that are not 
“picked” (affected) by PlanePick. The binary bit positions for PlaneOnOff are the same as 
those for PlanePick (lowest bit position specifies the lowest-numbered bit-plane). However, 
their meaning differs. For every plane position not selected by PlanePick, parts of the non- 
selected plane are filled with the value shown in the corresponding position of PlaneOnOff. 
The parts that are filled are the positions where there is a 1-bit present in the sprite’s image 
shadow. 


This provides a great deal of versatility. You can use a two-plane VSprite image as the source 
for many Bob images. Yet, because of the color combinations each contains, it may seem that 
there are several different images present. 


For example, assume that the data shown in the Bob layout above defines a two-bit-plane Bob 
image that selects its colors from color registers 0, 1, 4, and 5. To initialize the Bob and 
VSprite structures, you need to provide the following types of statements: 


/* data definition from example layout */ 
WORD BobData| |= { 
OxFFFF, 0x300C, 0xOFFO, 0x03CO, 0x0180, 
OxF FFF, 0x3FFC, 0x0C30, 0x03CO, 0x0180 


vs 


/* reserve space for the collision mask for this Bob */ 


WORD BobCollision[10]; 


my VSprite.Width — 1; /* sample image is 16 pixels wide (1 word) */ 
my VSprite.Height = 5; /* takes 5 lines to define each image of the Bob */ 
my VSprite.Depth = 2; /* only two bit-plane images are defined in BobData */ 


/* show the system where it can find the data image of the Bob */ 
my VSprite.ImageData = BobData; 


/* binary = 00101, means draw into only bit-planes 0 and 2 */ 
my VSprite.PlanePick = 0x05; 


/* binary = 00000, means for planes not picked, that is, 1, 3, and 4, 
«fill those planes with 0’s wherever there is a 1 in the sprite shadow mask 


wi 


my VSprite.PlaneOnOff = 0x00; 


/* where to put collision mask */ 
my VSprite.CollMask = BobCollision; 


140 Animation 


/* tell the system where it can assemble a sprite shadow */ 
/* point to same area as CollMask */ 
my Bob.ImageShadow = BobCollision; 


/* create the sprite collision mask for this Bob’s VSprite structure */ 
InitMasks( &myVSprite ); 


Whenever the system draws this Bob, it fills any position where there is a 1 in the sprite sha- 
dow with a O for any plane not selected by PlanePick. Therefore, the only binary combina- 
tions the Bob pixels can form are as shown below. Because of PlanePick, 1s can appear only 
at these two locations: 00101. So the color choices are limited to the following: 


Color Binary 
Selected Combination 


color 0 00000 
color 1 00001 
color 4 00100 
color 5 00101 


These color choices fulfill the requirements specified for the example. 


To select the position of a Bob, specify the y and x variables in the VSprite structure associ- 
ated with the Bob. For example: 


my VSprite.Y = 100; 
my VSprite.X = 100; 


BOB PRIORITIES 


This section describes the two choices you have for system priorities between Bobs. You can 
ignore the priority issue and let the system decide which Bob has the highest priority, or you 
can specify the drawing order yourself. When you specify the drawing order, you control which 
Bob the system draws last, and therefore, which one appears in front of other Bobs. 


Letting the System Decide Priorities 


If you want the system to decide, you set the Before and After pointers in the Bob data 
structure to zero. In this case, the system draws the Bobs in their y,x positional order on the 
screen. In other words, the system draws whichever object is on the screen and is currently the 
highest within the drawing area (lowest y coordinate value). If two objects have the same y 
coordinate, the object that has the lowest x coordinate value is drawn first. 
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The Bob drawn first has the lowest priority. The Bob drawn last has the highest priority 
because later objects overlap the objects drawn earlier. 


As you use the animation system to move objects past each other on the screen, you will notice 
that sometimes the objects switch priorities as they pass each other. For example, suppose you 
want the system to establish the priorities of the Bobs, and there are two Bobs defined in the 
system — myBob2 and myBob3. You set the Before and After pointers as follows: 


my Bob2.Before = 0; 
myBob2.After = 0; 
my Bob3.Before = 0; 
myBob3.After = 0; 


Specifying the Drawing Order 


If you wish to specify the priorities, simply specify the pointers as follows. Before points to the 
Bob that this Bob should be drawn before, and After points to the Bob that this Bob should 
be drawn after. This guarantees that Bob objects retain their relative priorities. 


For example, suppose you want to assure that myBob3 always appears in front of myBob2. 
You must initialize the Before and After pointers so that the system will always draw myBob3 
last; that is, after myBob2. 


myBob2.Before = &myBob3; /* draw Bob2 before drawing Bob3 */ 


myBob2.After = 0; /* draw Bob2 after no other Bob */ 
myBob3.After = &myBob2; /* draw Bob3 after drawing Bob2 */ 
myBob3.Before = 0; /* draw Bob3 before no other Bob */ 


/* draw nothing in particular after this Bob */ 


If you decide to specify the Before and After pointers for any one Bob in a group, then you 
must also at least set the Before and After pointers to zero for all of the rest of the Bobs in 
that group. 


For example, if there are ten Bobs and you only care that the system draws numbers 4, 6, and 
9 in that sequence, you must properly fill in the Before and After pointers for these three 
Bobs. If you do not care in which order the system draws the other seven Bobs, you need only 
initialize their Before and After pointers to a value of 0 to assure correct treatment by the 
system. 


You must properly point all Before and After pointers of a group to each other because the 
Bob that is the upper-leftmost becomes the first the system considers for drawing. The system 
follows the Before pointers until it finds one having a zero value, and draws that Bob first. It 
then draws other Bobs in the sequence you have specified. 
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In the example code sequence above, the comment “draw nothing in particular after this Bob” 
simply means that once the drawing sequence for this set of Bobs has been performed, the sys- 
tem still proceeds to find and draw all other Bobs currently linked into the GEL list. To con- 


tinue the drawing operation, the system simply goes on searching the list for the next Bob 
whose Before pointer is 0. 


Specifying Priority between Bobs and VSprites 


See ‘Topics Common to Both VSprites and Bobs” below for details. 


SAVING THE PLAYFIELD DISPLAY 


Once the system has drawn the Bobs, they become part of the playfield segment of the display. 
The image of a Bob overlays part of the background area. To move a Bob from one place to 
another, you must tell the system to save the background before it draws the Bob and to 
restore the background to its original condition when it moves the Bob. 


A variable called sprFlag in the VSprite structure contains a flag called SAVEBACK. To 


cause the system to save and restore the background for that Bob, set the SAVEBACK flag to 
1. 


In addition to the sprF lag variable, you must also tell the system where it can put this saved 
background area. For this, you use the SaveBuffer variable. For example, if the Bob is 48 


pixels wide and 20 lines high, and the system is drawing it into a playfield of five bit-planes, you 
must allocate space for storing the following: 


(48 pixels/16 pixels per word) * (20 lines) * (5 bit-planes) = 300 words 
To allocate this space, use the graphics function AllocRaster(). When you use AllocRaster() 


for this purpose, you can specify the area size in bits, so it may well be the most convenient way 
to reserve the space you need. For example: 


my Bob.SaveBuffer = AllocRaster(48,20 * 5); 
/* save space to store 48 bits times 20 words times 5 bit-planes */ 


Note that the AllocRaster() function rounds the width value up to the next integer multiple of 
16 bits. 
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USING BOB FLAGS 


The following sections describe the Bob flags. Some of these are in the VSprite structure asso- 
ciated with the Bob; others are in the Bob structure itself. The description of each flag tells 
the structure in which the flag is located. 


VSPRITE Flag 


If you are using the VSprite structure to describe a Bob, set VSPRITE to zero. 


The VSPRITE flag is located in the VSprite structure. 


SAVEBACK Flag 


If you want the GEL routines to save the background before the Bob is drawn and to restore 
the background after the Bob is removed, set the SAVEBACK (for ‘“‘save the background”’) flag 
in the VSprite structure to 1. 


If you set this flag, you must have allocated the buffer named SaveBuffer. 


OVERLAY Flag 


If the system should use the sprite shadow mask when it draws the Bob into the background, 
set the OVERLAY flag in the VSprite structure to 1. If this flag is set, it means that the 
background original colors show through in any section where there are 0 bits in the sprite sha- 
dow mask. Essentially, then, those O bits define areas of the Bob that are “‘transparent.”’ 


If you set the OVERLAY bit to a value of 0, the system uses the entire rectangle of words that 
define the Bob image and uses its contents to replace the playfield area at the specified y,x 


coordinates. 


If you set this flag, you must have allocated space for and initialized the ImageShadow sha- 
dow mask. See the section above called “Sprite Shadow Mask” for details on the shadow mask. 
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GELGONE Flag 


The system sets this flag in the VSprite structure to indicate when the Bob has been moved to 
y,x coordinates entirely outside of the “clipping region.”’ 


When an object crosses over certain specified boundaries in the drawing area, the system does 
not draw all of the object into the background but “clips” (truncates) it to those limits. At the 
time of this writing, the variables named topmost, bottommost, leftmost, and rightmost 
define the minimum and maximum y,x coordinates of this clipping region. 


When the system sets the GELGONE flag to a 1, you know that the object has passed entirely 
beyond those limits and that the system will not draw any part of the object into the drawing 
area. On the basis of that information, you may decide that the object need no longer be part 
of the GEL list and may decide to remove it to speed up the consideration of other objects. 


SAVEBOB Flag 


To tell the system not to erase the old image of the Bob when the Bob is moved, set the 
SAVEBOB flag in the Bob structure to 1. This lets you use the Bob like a paintbrush if you 
wish. It has the opposite effect of SAVEBACK. 


Note: It takes longer to preserve and restore the raster image than simply to draw a new Bob 
image wherever required. 


BOBISCOMP Flag 


If this Bob is part of an AnimComp, set the BOBISCOMP flag in the Bob structure to 1. If 
the flag is a 1, you must also initialize the pointer named BobComp. Otherwise, the system 
ignores the pointer, and it may be left alone. See ’’Animation Structures and Controls” for a 
discussion of AnimComps. 


BWAITING Flag 


When a Bob is waiting to be drawn, the system sets the BWAITING flag in the Bob structure 
to 1. This occurs only if the system has found a Before pointer in this Bob’s structure that 
points to another Bob. Thus, the system flag BWAITING provides current draw-status to the 
system. Currently, the system clears this flag on return from each call to DrawGList(). 
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BDRAWN Flag 


The BDRAWN system status flag in the Bob structure tells the system that this Bob has 
already been drawn. Therefore, in the process of examining the various Before and After 
flags, the drawing routines may determine the drawing sequence. Currently, the system clears 
this flag on return from each call to DrawGList(). 


BOBSAWAY Flag 


To initiate the removal of a Bob during the next call to DrawGList(), set BOBSAWAY to 1. 
Either you or the system may set this Bob structure system flag. The system restores the 
background where it has last drawn the Bob. The system will unlink the Bob from the system 
GEL list the next time DrawGList() is called unless you are using double-buffering. In that 
case, the Bob will not be unlinked and completely removed until two calls to DrawGList() 
have occurred and the Bob has been removed from both buffers. 


BOBNIX Flag 


When a Bob has been completely removed, the system sets the BOBNIX flag to 1 on return 
from DrawGList(). In other words, when the background area has been fully restored and the 
Bob has been removed from the GEL list, this flag in the removed Bob is set toa 1. BOBNIX 
is significant when you use double-buffering, because once you ask that a Bob be removed, the 
system must remove it from the active drawing buffer and from the display buffer. Once 
BOBNIX has been set for a double-buffered Bob, it has been removed from both buffers and 
you are free to reuse it or deallocate it. 


This flag is in the Bob structure. 


SAVEPRESERVE Flag 


The SAVEPRESERVE flag is a double-buffer version of the SAVEBACK flag. If you are using 
double-buffering and wish to save and restore the background, you set SAVEBACK to 1. 
SAVEPRESERVE is used by the system to indicate whether the Bob in the ‘other’ buffer has 
been restored; it is for system use only. 
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ADDING A BOB 


To add a Bob to the system GEL list (the same list you created for VSprites using 
InitGels()), you use the AddBob() routine. It is advisable that you initialize the different 


variables you plan to use within the Bob structure before you ask that the system add this 
Bob to the list. 


For example: 


struct GelsInfo my GelsInfo; 


struct VSprite dummySpriteA, dummySpriteB; 
struct Bob myBob; 


/* done ONCE, for this GelsInfo */ 
InitGels( &dummySpriteA, &dummySpriteB, &myGelsInfo ); 


/* here initialize the Bob variables * / 


AddBob( &myBob, &rastport ); 


REMOVING A BOB 


Two methods may be used to remove a Bob. This section describes the system routine for each 
method. 


The first method uses the RemBob() routine. You call this routine as follows: 


RemBob ( &myBob, &rastport ); 


RemBob() causes the system to remove the Bob during the next call to DrawGList() (or two 


calls to DrawGList() if the system is double-buffered). RemBob() asks the system to remove 
the Bob “at its next convenience.”’ 


The second method uses the RemIBob() routine. For example: 


RemIBob ( &myBob, &rastport, &viewport ); 


RemIBob() tells the system “remove this Bob immediately!” It causes the system to erase the 
Bob from the drawing area and causes the immediate erasure of any other Bob that had been 
drawn subsequent to this one. The system then unlinks the Bob from the system GEL list. To 


redraw the Bobs that were drawn on top of the one just removed, you must make another call 
to DrawGList(). 
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GETTING THE LIST OF BOBS IN ORDER 


Like the list of VSprites, the list of GELS must be in the proper y,x sorted order from top of 
screen to bottom and from left to right. The system uses the position information to decide 
drawing sequences if you have not specified otherwise by using the Before and After pointers. 
You must therefore assure that the GEL list is sorted before you ask the system to display the 
Bobs. 


To sort the GEL list, you call SortGList(). For example: 


SortGList( &rastport ); 


DISPLAYING BOBS 


This section provides the typical sequence of operations for drawing the Bobs on the screen. It 
is very similar to that shown for VSprites, as both Bobs and VSprites are GELS and are part 
of the same list of controlled objects. 


Specifically, the system automatically synchronizes the drawing routines to the display beam 
and may not require that the display be turned off during the update. If large Bobs or many 
Bobs are created, you may be interested in double-buffering. See the section called ‘‘Double- 
Buffering” in this chapter for details. 


When you call DrawGList(), the system actually draws any Bobs on this list into the area you 
have specified. The system saves the backgrounds if you have provided for the save and then 


performs the drawing sequence in the order you requested. To initiate this drawing, call 
DrawGList(). For example: 


struct RastPort *rp; 
struct ViewPort *vp; 


DrawGList(rp, vp); /* draw the elements */ 


CHANGING BOBS 


You can change the following characteristics of Bobs: 
o To change their appearance, change the pointer to the ImageData in the associated 


VSprite structure. Note that the change in the ImageData pointer also requires a 
change in the ImageShadow or a recalculation of the object mask, using InitMasks(). 
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o To change their color choices, change their PlanePick and/or PlaneOnOff values; 
also change the depth parameters if the sprite image has multiple planes defined. 


o To change the location in the drawing area, change the y,x values in the associated 
VSprite structure. 


o To change the object priorities, change the drawing sequence by altering the Before 
and After flags in the Bob structures. 


o To change the Bob into a paintbrush, set the SAVEBOB flag to a 1 in the Bob 
structure. 


Note: Neither these nor other changes actually happen until you call SortGList() and then 
DrawGList(). 


DOUBLE-BUFFERING 


Double-buffering is the technique of supplying two different memory areas in which the drawing 
routines may create images. The system displays one memory space while you are drawing into 
the other area. This assures that you never see any display fields on the screen that consist 
partly of old material and partly of new material. 


The system animation routines use an extension that you establish to the Bob structure. Also, 


if you do not care to use double-buffering, you need not tie up precious memory resources for 
unneeded variable storage space. 


To find whether a Bob is to be double-buffered, the system examines the pointer named 
DBuffer in the Bob structure. If this pointer has a value of 0, the system does not use 


double-buffering for this Bob. 


Note: If you do not wish to use double-buffering, you must initialize the DBuffer pointer to 
zero. For example: 


myBob.DBuffer = 0; /* do this if this Bob is NOT double-buffered */ 


The next section discusses several other variables that you must describe if you want to use 


double-buffering. Note: if any of the Bobs are double-buffered, then all of them must be 
double- buffered. 
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Variables Used in Double-Buffering 


To use double-buffering for a given Bob, you must provide a data packet for the system to 
store some of the variables it needs to handle double-buffering. This data packet is a structure 
named DBufPacket that consists of the following variables: 


BufY, BufX 
System variables that let the system keep track of where the object was located “‘last 
screen” (as compared to the Bob structure variables called oldY and oldX that tell 
where the object was two screens ago). BufY and BufX provide for correct restoration 
of the background within the currently active drawing buffer. 


BufPath 
System variable related to the drawing order used to draw this Bob into the back- 
ground. BufPath assures that the system restores the backgrounds in the correct 


sequence; it relates to the system variables DrawPath and ClearPath (found in this 
Bob’s VSprite structure). 


BufBuffer 


You must set this field to point to a buffer as big as this Bob’s SaveBuffer to allocate 
separate space for buffering the background on which you are drawing the Bob. This 


buffer is used to store the background for later restoration when the system moves the 
object. 


The next section shows how to pull all these variables together to make a double-buffered Bob. 


Creating a Double-Buffered Bob 


To create a double-buffered Bob, you must initialize all of the normal Bob variables and 
pointers and execute a code sequence similar to the following: 


struct DBufPacket myDBufPacket; 

/* allocate a DBufPacket for myBob */ 

/* same size as previous example in “Saving the Playfield Display” */ 
myDBufPacket.BufBuffer = AllocRaster( 48, 20 * 5 ); 


/* tell Bob about its double buff status */ 
myBob.DBuffer = myDBufPacket; 
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BOB OPERATIONS SUMMARY 


The following steps are involved in defining, moving, and displaying a Bob: 
o Define a RastPort structure for the drawing routine to use. 


o Initialize the GEL system (call InitGels()) for this RastPort. You only need to do 
this once. 


o Create and link a Bob and a VSprite structure. 
o Define the following Bob parameters: 

- Height 

- Width 

- Depth 

- Position 

- Where to find ImageData data 

- Which planes to pick for writing this Bob 

- How to treat the planes not picked 

- VSprite structure flags to show that this is a Bob 

- Space for the sprite shadow 


- Pointer to a DBufPacket if you want to use double-buffering (otherwise, make 
this pointer a NULL (0) value) 


o Call InitMasks() to create the sprite shadow. 
o Add the Bob to the GEL list. 
o Change the Bob appearance by 

- Changing the pointer to ImageData 


- Changing its height, width or depth 
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o Change the Bob colors by 

- Changing the playfield color set 

- Changing PlanePick and PlaneOnOff 
o Move the Bob by defining a new y,x position. 
o Display the Bob by calling: 

-  SortGList(); 

- DrawGList(); 


Now that you’ve mastered the basics of handling VSprites and Bobs, you may want to find 
out about some of the interactions between the two and how to cope with these interactions. 
Or, you may want to skip these advanced topics and read about software collisions, clipping, 
and adding new features in ‘“‘VSprite and Bob Topics”’ below. 


BOB ADVANCED TOPICS 


How Bob Colors Are Controlled 


Bobs do not use the SprColor pointer. To determine the color of a Bob, you use the existing 
colors in the 32-entry color table. The lower 16 of the 32 possible color selections (registers 0- 
15) are always dedicated to playfield color selections, providing 16 unique colors for the Bobs, 
since they are playfield objects. 


However, the playfields and the VSprites share the upper 16 of the 32 color entries (registers 
16-31). If you are using five bit-planes to display the Bobs, any Bob with a pixel whose color 
value exceeds 15 may change color if the virtual sprites are running at the same time. 


Note: This also applies to any static part of the display area (the playfield), whether a Bob or 
simply part of the background display, for which a five- or six-bit-plane image is used if the 
color number for a specific pixel exceeds the value of 15. 


To explain further, the virtual sprite routines, notably SortGList() and DrawGList(), work 
together to decide which real sprite will be used at any point on the screen. DrawGList() 
makes up a Copper instruction list to change the contents of the upper 16 color registers, 
perhaps several times within a single display field. Therefore, depending on where a Bob image 
is on the screen relative to a virtual sprite, and depending on its color content, a Bob may take 
on different colors (perhaps even within only a part of its body). 
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To minimize color interactions between Bobs and virtual sprites, take the appropriate precau- 
tions: 


o Limit the background to four or fewer bit-planes and thus limit the Bob color choices 
to 16 or fewer. 


o Use five bit-planes, but specify Bob colors or background colors from the colors 0 
through 15 or 16, 20, 24, or 28 only. Colors 16, 20, 24, and 28 are used neither by real 
sprites nor by virtual sprites and are treated as transparent areas. Therefore, if you use 
only these colors for Bobs, the simultaneous use of virtual sprites will not affect the 
Bob or background colors. 


o Use sprRsrvd to ‘“‘fence-off’’ certain sprite pairs, so you can also use their colors for 


Bobs. 


Topics Common to Both VSprites and Bobs 


DETECTING GEL COLLISIONS 


To detect collisions between graphics elements, you use the DoCollision() routine. DoColli- 
sion() determines if there are any pixels of one graphics element currently touching those of 
another graphics element or if any of the graphics elements have passed outside of specified 
screen boundaries. 


Whenever there is a collision, the system performs one of 16 possible collision routines. The 
addresses of the collision routines are kept in a table called the collision handler table. DoCol- 
lision() examines the HitMask and MeMask of each of the VSprite structures in the GEL 
list and determines if there is a collision between any two GELS. It then calls the collision- 
handler routine at the table position corresponding to the bits in the HitMask and MeMask, 
as outlined below. 


Note: The current form of these routines does not use the built-in hardware collision detection. 
You may, if you wish, reserve one or more sprites for your own use and move them using your 
own routines. When specific sprites have been reserved for your own use, you may choose to 
use the hardware collision detection to sense collisions between your own objects and other on- 
screen elements. See the Amiga Hardware Reference Manual for information about hardware 
collision detection. 
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Default Kinds of Collisions 


Two kinds of software collisions are handled by the collision routines: boundary hits and GEL- 


to-GEL hits. 


You can set up routines to handle as many as 16 different kinds of collisions using the VSprite 
structure MeMask and HitMask. When you call a collision routine, you give it certain kinds 
of information about the colliding elements, as described in the next two sections. 


Boundary Hits 


During the operation of the DoCollision() routines, if you have enabled boundary collisions for 
a GEL and that GEL crosses a boundary, the system calls the boundary-hit routine you have 


defined. Note that the system calls the routine once for each GEL that has gone outside of the 
boundary. 


The system will call your routine with the following two arguments: 
o A pointer to the VSprite structure of the GEL that hit the boundary 
o A flag word containing one to four bits set, representing top, bottom, left and right 


boundaries, telling you which one or more boundaries it has hit or exceeded. To test 


these, use the names TOPHIT, BOTTOMHIT, LEFTHIT, and RIGHTHIT. 


GEL-to-GEL Collisions 


If, instead of a GEL-to-boundary collision, DoCollision() senses a GEL-to-GEL collision, the 
system calls your collision routine with the following two parameters. They will be different 
from those in the GEL-to-boundary collision. 


o Address of the VSprite structure that defines the uppermost (or leftmost if y coordi- 
nates are identical) object of a colliding pair 


o Address of the VSprite structure that defines the lowermost (or rightmost if y coordi- 
nates are identical) object of a colliding pair 
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Handling Multiple Collisions 


When multiple elements collide within the same display field, the following set of sequential calls 
to the collision routines occurs: 


o The system issues each call in a sorted order for GELs starting at the upper left-hand 
corner of the screen and proceeding to the right and down the screen. 


o For any two colliding graphics elements, the system issues only one call to the collision 
routine for this pair. The system bases the collision call on the object that is the 
highest and leftmost of the pair on the screen. 


Preparing for Collision Detection 


Before you can use the system to detect collisions between GELS, you must initialize the table 
of collision-detection routines. This table points to the actual routines that you will use for the 
various collision types you have defined. Also, you must prepare certain variables and pointers 
within the VSprite structure: BorderLine, CollMask, HitMask, and MeMask. 


Building a Table of Collision Routines 


To add to or change the table entries for the collision routines, call the SetCollision() routine. 
The syntax for this routine follows: 


SetCollision( num, routine, Ginfo) 
where 


num 
is the collision vector number 


routine 
is a pointer to the user collision routine 


GInfo 


is a pointer to a GelsInfo structure 


When the View structure is first initialized, the system sets all of the values of the collision rou- 
tine pointers to zero. You must initialize those table entries so that they correspond to the 
HitMask and MeMask bits that you have set. Only those table entries can cause the system 
to call the collision routines. 
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You must also allocate a table, pointed to by GelsInfo, for vectors. The table needs to be only 
as large as the number of bits for which you wish to provide collision processing. For example: 


VOID myCollisionRoutine( GELM, GELN ) /* sample collision routine */ 
struct VSprite *GELM; 


struct VSprite *GELN; 
{ 


printf(”GEL at %lx has hit GEL at %lx”, (long)GELM, (long)GELN); 
} 


/* sample initialization */ 
Ready Gels(gelsinfo, rastport);/* use exec_support function */ 
SetCollision( 15, myCollisionRoutine, &gelsinfo ); 


Collision Mask 


The variable named CollMask is a pointer to a memory area that you have reserved for hold- 
ing the collision mask of a GEL. A collision mask is usually the same as the shadow mask of 
the GEL, formed from a logical-or combination of all 1 bits in all planes of the image. Figure 
3-3 shows an example collision mask. 


If this is the image in: Then its CollMask its: 


Plane 1 Plane 2 
1111111111117 171111111171111171 





Figure 3-3: A Collision Mask 


You normally use this collision mask to control drawing of the object and to define essentially 
the positions where there is an image bit present. After you have defined the collision mask 


through the routine InitMasks(), you may specify that the system is to store both the shadow 
mask and the collision mask in the same location. 


For example, here are typical program statements to reserve an area for the sprite shadow, ini- 
tialize the pointer correctly, and then specify that the system uses the same mask for collisions 
(this example assumes a two-word-wide, four-line-high image): 
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/* reserve 8 16-bit locations for sprite 
* shadow to be stored into by the system. 
* 
/ 
WORD myShadowData{8]; 
/* and point to it */ 
my VSprite.ImageShadow = myShadowData; 
/* collision mask is same as shadow */ 
my VSprite.CollMask = myShadowData; 


As an alternative, for certain game-oriented applications, you may design certain objects with 
sensitive regions and non-sensitive regions. Suppose you have an object, such as a spaceship, 
with an outer layer that is to be non-sensitive and an inner core that is to register collisions for 
the overall object. You would define your shadow mask with 1 bits in the appropriate positions 
to define the desired sensitive area. An example using this type of image is shown in figure 3-4. 


If the current CollMask is: Perhaps you only want to 
have a sensitive area which 
has this shape: 


1111111111111 





Figure 3-4: Shadow Mask for a Sensitive Area 


BorderLine Image 


For fast collision detection, the system uses the pointer named BorderLine. BorderLine 
specifies the location of the horizontal logical-or combination of all of the bits of the object. It 
may be compared to taking the whole object and squashing it down into one single horizontal 
line. Here is a sample of an object and its BorderLine image: 
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OBJECT 


001100001100 
000110011000 
000011110000 
000110011000 
001100001100 


BORDERLINE IMAGE 
001111111100 
The borderline image establishes a single set of words (represented by the collision mask) that 
have 1 bits at the outermost edges of the object. Using this squashed image, the system can 
quickly determine if the image is touching the left or rightmost boundary of the drawing area. 
To establish the borderline data, you make a system call to InitMasks(). Before calling 
InitMasks(), you provide the system with a place to store the image it creates. The size of the 


data area you reserve must be at least as large as the image is wide. 


In other words, if it takes three 16-bit words to hold the width of a GEL, then you must reserve 
three words for the borderline image. For example: 


/* reserve some space for the border image to be stored for this Bob */ 
WORD myBorderLineData/|3]; 


/* tell the system where to put the BorderLine image it will form */ 
my VSprite.BorderLine = myBorderLineData; 


Note: Both Bobs and VSprites participate in the software collision detection. 
The next section tells how to turn on the software collision detection independently for each 


GEL. 


Software Collision-Detect Control Variables 


You can enable or disable software collision detection for each GEL independently. In addition, 
any time the system senses a collision, you can specify which of 16 possible collision routines 
you wish to have automatically executed. The HitMask and MeMask variables in the 
VSprite structure let you specify the relationships between different GELS. 


158 Animation 


By specifying the bits in these masks, you can control how and when the system senses colli- 
sions between objects. The collision testing routine, in addition to sensing an overlap between 
objects, also uses these masks to determine which routine(s) (if any) the system will call when a 
collision occurs. 


When the system determines a collision, it ands the HitMask of the upper-leftmost object in 
the colliding pair with the MeMask of the lower-rightmost object of the pair. The bits that 
are ls after the and operation choose which of the 16 possible collision routines to perform. 


o If the collision is with the boundary, bit 0 is a 1 and the system calls the collision han- 
dling routine number 0. You assign bit 0 to the condition called ‘‘boundary hit.” The 
system uses the flag called BORDERHIT to indicate that an object has landed on or 
moved beyond the outermost bounds of the drawing area (the edge of the clipping 
region). 


o If you set any one of the other bits (1 to 15), then the system calls the collision han- 
dling routine corresponding to the set bit. 


If more than one bit is set in both masks, the system calls the vector corresponding to the right- 
most bit. 


Using HitMask and MeMask 


This section provides an example of the use of the HitMask and MeMask to define a new 
form of collision detection. 


Suppose there are two classes of objects that you wish to control on the screen: ENEMYTANK 
and MYMISSILE. Objects of class ENEMYTANK should be able to pass across one another 
without registering any collisions. Objects of class MYMISSILE should also be able to pass 
across one another without collisions. However, when MYMISSILE collides with ENEMYTANK 
or ENEMYTANK collides with MYMISSILE, the system should process a collision routine. 


Choose a pair of collision detect bits not yet assigned within MeMask, one to represent 
ENEMYTANK, the other to represent MYMISSILE. You will use the same two bits in the 
corresponding HitMask. 
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MeMask  HitMask 


Bit # 21 21 

GEL #1 01 10 ENEMYTANK 
GEL #2 01 10 ENEMYTANK 
GEL #3 1 0 01 MYMISSILE 


In the example, bit 1 represents ENEMYTANK objects. In the MeMask, bit 1 is a 1 for GEL 


#1 and says “I am an ENEMYTANK.” Bit 2 is a zero says this object is not a MYMISSILE 
object. 


In bit 1 of the HitMask of GEL #1, the O bit there says, “I will not register collisions with 
other ENEMYTANK objects.’’ However, the 1 bit in bit 2 says, “I will register collisions with 
MYMISSILE objects.” 


Thus when a call to DoCollision() occurs, for any objects that appear to be colliding, the sys- 
tem ands the MeMask of one object with the HitMask of the other object. If there are non- 
zero bits present, the system will call one (or more) of your collision routines. 


In this example, suppose that the system senses a collision between ENEMYTANK #1 and 
ENEMYTANK #2. Suppose also that ENEMYTANK #1 is the top/leftmost object of the 
pair. Here is the way that the collision testing routine performs the test to see if the system will 
call any collision-handling routines: 


Bit # 


| bo 
| == 


ENEMYTANK #1 MeMask 0 1 


p—_ 
© 


ENEMYTANK #2 HitMask 


Result of and 0 O 


Therefore, the system does not call a collision routine. 


Suppose that DoCollision() finds an overlap between ENEMYTANK #1 and MYMISSILE, 
and MYMISSILE is the top/leftmost of the pair: 
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Bit # 2 1 
MYMISSILE #1 MeMask 1 0 
ENEMYTANK #2 HitMask 1 0 
Result of and 1 0 


Therefore, the system calls the collision routine at position 2 in the table of collision-handling 
routines. 


BOB/VSPRITE COLLISION BOUNDARIES WITHIN A RASTPORT 


To specify a region within the RastPort (drawing area) that the system will use to define the 
outermost limits of the GEL boundaries, you use the following variables: topmost, bottom- 
most, leftmost, and rightmost. The DoCollision() routine tests these boundaries when 
determining collisions within this RastPort. 


Here is a typical program segment that assigns the variables correctly. It assumes that you 
already have a RastPort structure named myRastPort. 


my RastPort- > GelsInfo->topmost = 50; 

my RastPort- > GelsInfo- >bottommost = 100; 
my RastPort- > GelsInfo-> leftmost = 80; 

my RastPort- > GelsInfo->rightmost = 240; 


The current release of the system software makes use of the clipping-rectangle feature of the 
RastPorts to create clipping to the RastPort’s limits. However, you may base the “boundary 
collision” limits for this RastPort on the variables shown here. 


ADDING NEW FEATURES TO BOB/VSPRITE DATA STRUCTURES 


This section describes how to expand the size and scope of the VSprite or Bob data structures. 
In the definition for the VSprite and the Bob structures, there is an item called UserExt at 
the end of the structure. If you want to add something to these structures (specifically, a user 
extension), you simply specify that the UserExt variable is composed of a specific type. 


Why would you want to add things to the structure? When the DoCollision() routine passes 


control to your collision-processing function, you may wish to change some variable associated 
with the GEL. The example below places speed and acceleration figures with each GEL. When 
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you perform the collision routine, it exchanges these values between the two colliding objects. 
The system uses additional routines during the no-collision times to calculate the new positions 
for the objects. 


You could define a structure similar to the following: 


struct myInfo { 
short xvelocity; 
short yvelocity; 
short xaccel; 
short yaccel; 


3 


that you want to have associated with each of the GELS. These variables are, for example, 
your user extensions. 


You would also provide the following line: 


For VSprites: 
#define VUserStuff struct myInfo 


For Bobs: 
#-define BUserStuff struct myInfo 


For Anim Obs: 
#-define AUserStuff struct myInfo 


When the system is compiling the graphics/gels.h file with your program, the compiler substi- 
tutes “struct myInfo’’ everywhere that UserExt is used in the header. The structure is thereby 
customized to include the items you wish to associate with it. 


Note: The header files include the following UserStuff variables for VSprites, Bobs, and 
AnimObs: 


VSprites: VUserStuff 


Bobs: BUserStuff 
AnimObs: AUserStuff 
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Animation Structures and Controls 


This section outlines the system animation support for Bobs only. In the section called ‘‘Bob 
Priorities”’ you learned how to control the priorities of Bobs with respect to one another by 
specifying the drawing sequence. The following sections explain how to link objects and how to 
specify an animation completely by linking different views of objects into a sequence. 


To perform animation, an artist produces a series of drawings. Each drawing differs from the 
preceding one so that when they are sequenced, the object appears to move naturally. An ani- 
mation in the Amiga consists of a linked list of the components of the animation object and 
each component as a linked list of the different drawings in its sequence. 

To perform the actual animation, you make a call to a system routine called Animate(). When 
you call Animate(), the software follows all of your animation instructions and ‘‘moves” the 
objects accordingly. When you next call DrawGList(), the system draws all objects in the 


position caused by your calls to Animate(). Essentially, Animate() simply manipulates a set 


of instructions in a set of object lists. Only when the system draws the objects are your instruc- 
tions displayed visually. 


Remember, the system draws the currently sorted objects from its GELS list. 


CHARACTERISTICS OF THE ANIMATION SYSTEM 


The animation system lets you define a series of Bobs, which it then links into an overall 
object. The combined object consists of one or more Bobs that comprise the overall object and 
additional Bobs that comprise alternate appearances (animation sequences) for the various com- 
ponent parts. 


You specify the following: 
o The initial appearance of an overall object by defining Bobs as its components 
o Alternate views of various components by defining additional Bobs 


o The drawing precedence for the initial appearance of the object among the Bobs that 
comprise the initial appearance 


The animation system does the following: 


o Moves all linked objects simultaneously 
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o Maintains inter-object prioritization 


o Sequences alternate views to provide animation through user-specified timing variables 


KEEPING TRACK OF GRAPHIC OBJECTS 


The section called “Getting the List of Bobs in Order” described how the system maintains a 
list of Bobs to draw on the screen according to your instructions. The animation system selec- 
tively adds items to and removes items from this list of screen objects during the Animate() 


routine. The next time you call DrawGList(), the system will draw the current Bobs in the 
list into the selected RastPort. 


CLASSES OF ANIMATION OBJECTS 


You have two classes of animation objects to consider: AnimObs and AnimComps. The 
AnimOb is the primary animation object. It is this object whose position you are specifying 
with respect to the coordinates of the drawing area. Actually, an AnimOb itself contains no 
imagery. It is merely the top-level data structure that organizes the components that it 
manages and that specifies a position relative to which everything else is drawn. The 
AnimComp, on the other hand, is an animation component — for example, an arm, leg, or 
head — of an animation object. The animation object consist of animation components that 
you specify. 


To define an AnimOb, you specify several characteristics of the primary animation object, 
including the following: 


o The initial position of this object 

o Its velocity and acceleration in the X and Y directions 

o How many calls to DrawGList() you have made while this object has been active 
o A pointer to a special animation routine related to this object (if desired) 

o <A pointer to the first of its animation components 


o Your own extensions to this structure, if desired 
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POSITIONS OF ANIMATION OBJECTS 


The next two sections tell how to specify the initial position of an AnimOb and _ its 
AnimComp. 


Position of an AnimOb 


To specify a registration point within the drawing area (the RastPort) for all components, you 
use the variables AnX and AnY in the AnimOb structure. Figure 3-5 illustrates that each 
component has its own offset from the object’s registration point. 


RastPort Drawing Area 


Y increases from 
top to bottom of 


Registration point drawing area 


(reference) for all 
parts of an AnimOb. 


X increases from left to right 





Figure 3-5: Specifying an AnimOb Position 


Position of an AnimComp 


To specify where the component is to be located relative to the position of the registration point, 
you use variables in the AnimComp structure. When you move the animation object, all of 
the component parts of this animation object move with it, as illustrated in figure 3-6. 
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XTrans 


RastPort Drawing Area 


Y Trans Object #2 


X Trans 


Y Trans 
Object #3 





Figure 3-6: Specifying an AnimComp Position 


To specify the relative placement of a component with respect to the registration point of the 
AnimOb, you assign the values of X Trans and YTrans in the AnimComp structure. These 


values can be positive (as shown for object #3), negative (as shown for object #2), or zero (as 
shown for component #1) in figure 3-6 above. 


Now that the system knows the position of the objects and components you wish to animate, 
you can tell the system how to animate them. The following sections describe the animation 
choices provided for you by the system. 


ANIMATION TYPES 


The system software allows two forms of animation: sequenced drawing and motion control. 


Sequenced Drawing 


In sequenced drawing, an artist produces a sequence of views of an object, where each view is a 
modification of a preceding view. To produce apparent motion of the object, the artist draws 


each new view of an object at a position somewhat farther from a common reference point than 
the preceding view. 
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If an animation is to be continuous, based on a repeating sequence, then the last drawing in the 
series should allow the first drawing in the series to be the next in line, creating a continuity of 
motion. Figure 3-7 shows four out of a sequence of drawings that could use this technique for 
animation. (The other intermediate steps are not shown.) 


As you will notice, each of the drawings, reading from right to left, is a little closer to its regis- 
tration point (the reference point). The upper level of the figure shows the figures individually. 
The lower level shows the figures overlaid, demonstrating that smooth motion would be possi- 
ble. To the left of the overlaid figures is a second set, drawn in gray, representing the reinitiali- 
zation of the sequence of drawings, beginning with number one. 


Animator’s Registration Marks 


The figure moves 
as each of the 
sequenced 
drawings is 
produced in 
place of the 
previous one 

in the sequence. 


When the sequenced 
drawing reaches the end 
and restarts with drawing 1 
again, the registration mark 
is moved so that a smooth 
transition is formed. 





Figure 3-7: A Sequenced Drawing 
Sequenced animation often consists of a closed “ring” of drawings. When the last drawing of 
the sequence has been completed, the first drawing in the sequence is repeated again, becoming 


the first in the next part of the animation, offset by a specific position in space. 


To specify sequenced drawing, use the variables called compFlags in the AnimComp struc- 
ture, and RingX Trans and RingYTrans in the AnimOb structure. 
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To move the registration mark to a new location, you set the RINGTRIGGER bit for a com- 
ponent in its compF lags variable. The system software adds the values of RingX Trans and 
RingYTrans found in the AnimOb structure to the values of AnX and AnyY of the head 
object (the registration mark), thereby moving the reference point to the new location. The 
next time you execute DrawGList(), the drawing sequence starts over again at the new loca- 
tion, mating properly with the final drawing of the sequence at the old registration mark. 


You usually set RINGTRIGGER in only one of the animation components in a sequence; how- 


ever, you can choose to use this flag and the translation variables in any way you wish. 


Motion Control 


In the second form of animation, you can specify objects that have independently controllable 
velocities and accelerations in the X and Y directions. Components can still sequence. Further- 
more, you can use ring and velocity simultaneously if you wish. 
The variables that control this motion are located in the AnimOb structure and are called: 

o YVel, XVel—the velocities in the y and x directions 

o Y<Accel, XAccel—the accelerations in the y and x directions 


Velocities and accelerations can be either positive or negative. 


The system treats the velocity numbers as though they are fixed-point binary fractions, with the 
decimal point fixed at position 6 in the word. That is: 


vvvvvvvvvv.efffff 


where v stands for actual values that you add to the x or y (AnX, AnY) positions of the object 
for each call to Animate(), and f stands for the fractional part. By using a fractional part, you 
can specify the speed of an object in increments as precise as 1/64th of an interval. 


In other words, if you set the value of XVel at 0x0001, it will take 64 calls to the Animate() 
routine before the system will modify the object’s x coordinate position by a step of one. The 


system requires a value of 0x0040 to move the object one step per call to Animate(). 


Each call you make to Animate() simply adds the value of XAccel to the current value of 
XVel, and YAccel to the current value of YVel, modifying these values accordingly. 
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Using Sequenced Drawing and Motion Control 


If you are using sequenced drawing, you will probably set the velocity and acceleration variables 
to zero. This allows you to produce the animation exactly in the form in which the artist has 
designed it in the first place. 


Consider an example of a person walking. As each foot falls, with sequenced drawing, it is posi- 
tioned on the ground exactly as originally drawn. If you include a velocity value, then the 
person’s foot will not be stationary with respect to the ground, and the person appears to 


“skate” rather than walk. If you set the velocity and acceleration variables at zero, you can 
avoid this problem. 


INITIALIZING THE ANIMATION SYSTEM 


To initialize the system, you must define a pointer to an AnimOb. The system uses this 
pointer to keep track of all of the real AnimObs that you create. The following typical code 
sequence accomplishes this: 


struct AnimOb *animKey; 


animKey = NULL; 


Note: Before you can use the animation system, you must call the routine InitGels(). There- 
fore, you must initialize the GEL system as well as the animation system. See the “Initializing 
the GEL System” section for details on InitGels(), the Bob-control system that eventually 
displays the objects that you manipulate. 


SPECIFYING THE ANIMATION OBJECTS 


To add animation objects to the controlled object list, you use the routine AddAnimOD(). 
Figure 3-8 shows how to build a list of controlled objects using this routine. The animKey 
always points to the object most recently added to the list. 
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M animKey — always points to the 
ie ee last AnimOb added 
ee to the list 
This AnimOb list 


Next AnimOb is the complete 
list of all of the 
Previous AnimOb AnimObs being 


nee handled by the 


Other AnimOb ee 
Variables added to 


a list 
Next AnimOb 
Previous AnimOb 


Other Typical 


Variables middle 
AnimOb 


Next AnimOb 
Previous AnimOb Null 


First 
Other AnimOb 
Variables added to 
a list 





Figure 3-8: Linking AnimObs into a List 


Next, you tell the system about the components that make up the object. 


SPECIFYING ANIMATION COMPONENTS 


As previously stated, each animation object consists of one or more individual component parts. 
The parts may be, for example, the body of an object, its arms, its legs, and so on. Not only 
does the system animator move parts from place to place, but it also offers different views of 
each of the parts. To specify the relationships between the individual parts and views of those 
parts, you initialize various pointers within the AnimComp structure. 


You use the pointers called PrevSeq and NextSeq to build a doubly-linked list of a set of ani- 


mation components used for sequenced drawing, as outlined above. In all cases, when you 
specify AnimComps, you must initialize these pointers to build the sequence that you wish the 
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system to follow for drawing the various views of this component. The ‘‘Animation Sequenc- 
ing” section below shows how the system uses these pointers. 


To link the components together into a whole object, use the pointers called PrevComp and 
NextComp. When you build an animation object, you must initialize the PrevComp and 
NextComp pointers for only the initial view of the animation object. Whenever the animation 
system senses that one of the animation objects has ‘“‘timed out’’ and switched to a new 
sequence of that component, the system automatically adjusts the PrevComp and NextComp 
pointers so that it retains the complete animation object. 


Figure 3-9 shows an animation object built of several components. The AnimOb points to the 
head component. Notice that the ‘“head’’ component may be any one of the components of the 
object. A pointer in the structure of the head component, in turn, points to the next one, and 
so on (building the initial view of the object). 


To point around the ring for each of the component sequenced views (although the objects do 
not necessarily have to form a ring), you initialize the sequence pointers NextSeq and 
PrevSeq. The animation system ignores the PrevComp and NextComp pointers for each of 
the non-current components. 
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ro . NON-CURRENT 
Next AnimOb CA ala additional views of 
Previous AnimOb designed by the user. each component, 


waiting to be used. 


HeadComp Next AnimComp 
Previous AnimComp Previous AnimComp 


Sequence Linkage Sequence Linkage 


Next AnimComp Next AnimComp 
Previous AnimComp Previous AnimComp 


Sequence Linkage Sequence Linkage 


Next AnimComp Next AnimComp 
Previous AnimComp Previous AnimComp 


Sequence Linkage Sequence Linkage 





Figure 3-9: Linking AnimComps To Form an AnimOb 


DRAWING PRECEDENCE 


The sequence in which you link the components in a list to define the object itself is immaterial. 
The system simply uses this list of components to define the overall object. To specify the 
drawing precedence for the objects in an animation object, you use the Before and After 
pointers in the Bob structure for the initial sequence of the animation object. 


If you refer to the description of adding Bobs in the section called ‘““Adding a Bob,” you will see 
that when you add Bobs to the system, the Before and After pointers control the drawing 
sequence and thereby the precedence of the objects. Once you have added the Bobs to the sys- 


tem with AddBob(), you must assign a fixed set of pointers to establish the correct drawing 
order. 


172 Animation 


Animation components may have several views, each of which points to a Bob structure. How- 
ever, only one of those views is actually “active” for that component at any one time, making 
up part of the overall animation object. The animation system adjusts the Before and After 
pointers of the Bob structure for each of the current views to maintain the sequence of drawing 
for each of the components the same as that you have defined for the initial view. Adjustments 
take place in the sequencing any time any one of the animation components ‘‘times out’? and 
shows a new sequence. Therefore, if you are defining Bobs as part of the animation system, 
you need only initialize the Before and After pointers within the Bob structure for the initial 
sequence of each of the components. 


You may wish to define multiple animation objects. To assure that one complete object always 
has priority over another object, you can use the initial sequence linkage to control this as well. 
You use the Bob Before and After pointers to link together the last AnimComp’s Bob of 
one AnimOb to the first AnimComp’s Bob of the next AnimOb. The system maintains the 
drawing order during calls to Animate() from that time onward. 


You may modify the drawing order during part of the animation (such as to make one object 
pass in front of another during one display sequence, then pass behind it on the next sequence). 
You can perform this kind of activity, if you wish, during an AnimORoutine or AnimCRoutine. 
See the section called ‘“Your Own Animation Routine Calls” for details. 


ANIMATION SEQUENCING 


To perform sequenced drawing, you must define the sequence in which you wish the drawings to 
be made. For each of the animation components, there is a set of pointers that allows you to 
define the exact sequence in which the drawings should appear. 


After a period of time that you have specified, which is separately controllable for each com- 
ponent, the system software automatically switches from the current drawing in the sequence to 
the next one. For this purpose, you provide three pieces of information in the AnimComp 
structure: pointers to the previous and next drawings in the sequence that you have defined, a 
user flag variable called Flags, and a TimeSet variable. 


After the specified time interval for each of the sequenced drawings, the system software 
switches to show the next drawing specified in the sequence. The next section shows how you 


specify the time. 


Figure 3-10 illustrates how the system uses the “next sequential image’”’ pointer to step from one 
image to the next at the specified time. 


If you set the RINGTRIGGER bit in the Flags variable, the system adjusts the reference point 
for the sequenced drawing. See the ‘““Sequenced Drawing” section above for details. 
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Sample Animation Sequence 


AnimComp 
alll AnimBob = Bob! . 


AnimBob = Bob2 


(also called ‘“Bob4’’) AnimBob = Bob 2 


NN AnimBob = Bob 3 a 


Notice that, in the sample shown, it is only 
necessary to store 3 images in order to 
allow a four image animation to be performed. 





Figure 3-10: Linking AnimComps for Sequenced Drawing 


SPECIFYING TIME FOR EACH IMAGE 


When you have defined all of your animation objects and components, you call the Animate() 
routine. To manipulate the objects, you set the variable called Timer in the AnimComp 


structure and you set a corresponding variable called TimeSet (also in the AnimComp struc- 
ture). 


When the system selects the animation component, the system copies the value currently in 
TimeSet into the variable named Timer. If Timer has a nonzero value when you call 
Animate(), then the current view of the animation component remains the active view for as 
many calls to Animate() as you specify with the value in Timer. When the Timer value 
counts down to zero, the system makes the next sequential view active. If you set the value in 
TimeSet to zero, Timer remains zero. Timer never triggers from a non-zero state and, there- 
fore, does not cause any change in the view. 
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When the system activates a new sequence component, it checks that component’s compF lags 
to see if the RINGTRIGGER flag bit is set. If so, the system performs ring processing, which 
means that it adds the values RingYTrans and RingX Trans to AnY and AnX respectively. 
See the section called ‘‘Animation Types” for details. 


Now let’s see how this process works in an actual animation. Let’s say that you are animating 
the figure of a man. As he walks across the screen, he swings his arm back and forth at a fixed 
rate. Assume that you have three drawings of the arm: swung forward, at a center position, 
and swung back. To animate the arm, you may follow these steps: 


1. Define four Bobs: the first for the forward swing, the second for the center, the third 
for the back swing, and the fourth centered again. 


2. Define four AnimComps, one for each of these Bobs. To link them together in a 
sequence (forward, center, back, center), use the PrevSeq and NextSeq pointers. 


3. Link one of the AnimComps in this sequence to the AnimComp that defines the 
body of the man, using the AnimComp, PrevComp, and NextComp pointers. 


4. Set the Timer variable for each sequenced AnimComp to a value appropriate for him 
to hold that pose. For example, three calls to Animate() for forward and back, and 
two calls for each of the two centered positions of his arm might be appropriate values. 


5. Set the value of XTrans and YTrans for each AnimComp to position the arm prop- 
erly with respect to the rest of the body for each sequence of the arm swing. 


6. Continue the arm sequence by setting the RINGTRIGGER bit in the flags variable of 
the last sequence, thereby triggering a return to the first view when the timer of the 
last view times out. 


Now, each time you call Animate(), the animation system checks all of the Timer variables, as 
well as calling your AnimCRoutines and AnimORoutines. When each of the Timer variables 
becomes a zero, the next sequenced view of the AnimComp replaces the current sequence. 
When an AnimComp becomes “current,’’ the value in its TimeSet variable is copied into its 
Timer variable. 


This also means that you have told the system two things: first, to remove the Bob of the 
current sequence from the system Bob list the next time you call DrawGList(); and second, to 
use the Bob representing the new sequence in its place. The system automatically copies the 
Bob Before and After pointers from the current sequence into the new sequence 
AnimComp’s Bob to assure that the object is still drawn in the same order, maintaining its 
priority relative to other objects in the drawing area. 
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YOUR OWN ANIMATION ROUTINE CALLS 


The AnimOb and AnimComp structures include pointers to your own routines that you want 
the system to call. If you want a routine to be called, you must specify the address of the rou- 
tine in this variable. If no routine is to be called, you must set this variable to zero. No values 
are passed to these routines, except a pointer to its AnimOb or AnimComp, respectively. 
However, because you set each AnimORoutine (the AnimOb routine) and AnimCRoutine (the 
AnimComp routine), you can use the extensions to the AnimOb or Bob or VSprite struc- 
tures to hold the variables you need for your own routines. 


Suppose you are creating the following animation: 


O 


A man is walking a dog down a street. There is a fireplug at one side of the screen. 
Let’s say you wish to change the appearance of the fireplug if the dog approaches too 


closely. You would, therefore, design an AnimORoutine to do a proximity check on the 
dog. 


To allow the fireplug to have different appearances, you might provide three individual 
views. One is normal, one is an intermediate view (comparable to the center arm-swing 
mentioned earlier), and the final view is a “strength pose,” saying ‘‘back off dog!”’ 


You may set the TimeSet and Timer variables for the “normal’’ appearance for the 
fireplug at zero. This means that it should never change from this appearance no 
matter how many calls to Animate() occur, as defined above. (If it is already zero, it 
will not decrement; therefore, it can never go from non-zero to zero). 


You may set the TimeSet variable for the intermediate view to 1 (stay in the inter- 
mediate pose for only one call to Animate()). In addition, you may set the TimeSet 
variable for the strength pose to 10 (stay strong for ten calls to Animate()). 


For each call to Animate(), the AnimORoutine for the fireplug checks how close the 
dog has approached. If it is within a certain range, the AnimORoutine changes the 
Timer variable for the normal fireplug pose to a 1. 


The next call to Animate() finds a value of 1 in the Timer variable and decrements it. 
This makes a value of 0, forcing a change to the next sequence (the intermediate pose). 
The system will remove the normal pose Bobs from the system Bob list it is to draw, 
and the next call to DrawGList() will therefore draw the intermediate pose instead. 


The next call to Animate() finds a value of 1 in the Timer variable for the intermedi- 
ate pose and decrements it, causing a change to the strength pose. The fireplug remains 
in the strength pose for ten calls to Animate(), returning through the intermediate 
pose for one call, then to the normal pose again. 
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o Now that the Timer value has become zero again, the fireplug returns to the original 
state, staying in its normal pose until the dog again approaches within range. 


MOVING THE OBJECTS 


When you have defined all of the structures and have established all of the links, you can call 
the Animate() routine to move the objects. Animate() adjusts the positions of the objects as 
described above, and calls the various subroutines (AnimCRoutines and AnimORoutines) that 
you have specified. 


After the system has completed the Animate() routine, as the screen objects have been moved, 
their order in the graphics objects list may possibly be incorrect. Therefore, as always, before 
ordering the system to redraw the objects, you must sort them first. 


If you perform DoCollision() when the system has newly positioned the objects after your call 
to Animate(), your collision routines may also have an effect on the ultimate position of the 
objects. Therefore, you should again call SortGList() to assure that the system correctly ord- 
ers the objects before you call DrawGList(), as illustrated in the following typical call 
sequence: 


/* ... setup of graphics elements and objects */ 


Animate( key, rp ); /* ”»move” objects per instructions */ 
SortGList( rp ); /* put them in order */ 

DoCollision( rp ); /* software collision detect/action */ 
SortGList( rp ); /* put them back into right order */ 


DrawGList( vp, rp ); /* draw into current RastPort */ 


Complete Example Program 


The following program produces a single-buffered display with two Bobs and two Vsprites. 
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/* SAMPLE PROGRAM THAT USES GELTOOLS TO PRODUCE A DOUBLE BUFFERED DISPLAY 
* SCREEN CONTAINING TWO BOBS AND TWO VSPRITES 
a 


* Author: David Lucas 
ay 


/* Leave this structure definition at the top. Look at gels.h. */ 
struct vinfo { 
short vx, vy; /* This VSprites velocity. */ 
short id; 


}: 
#define VUserStuff struct viInfo 


/* Things to notice: 


Default value in sprite/pl oe priority register has all 
hardware sprites having a higher priority than either of the 
two playfields. Areas containing color 0 of both the bob and 
veprite are shown as transparent (see hole in center of each). 


You can specify bob drawing order by using the before and after 
pointers, thereby always maintaining an apparent precedence of 
a bob over another. Re Vsprites.... because they are assigned 

entially from top of screen to bottom, in sprite numerical 
or er (0, 1, 2, 3 etc), and because the lowest numbered hardware 

rite has the highest video precedence, the sprite that is 

osest to the top of the screen always appears in front of the 
sprite beneath it. 


Without drape aie gaat 1 there would be flicker on the part 

of the bobs. Double buffering consists of writing into an area 
that is not reat displayed. Some of the flicker could have been 
alleviated by waiting for the video beam to reach top-of- frame 
before doing the drawing, but when the bobs are near the top, 

it makes it all the more difficult to draw without ap arent 

flicker in that case. Also note that multitasking wi 

occasionally upset even this plan in that it can delay the 

drawing operation until the beam is in the area that is being drawn. 


ne 


OIG IUISI III IIIIOIOIOOOOIOIOIIII IK 
* A sprite and a bob on a screen. 
a 


#include “intuall .h" 


#define SBMWIDTH 320 /* My screen size constants. */ 
#define SBMHEIGHT 200 
#define SBMDEPTH 4 


#define RBMWIDTH 330 /* My rastport size constants. */ 
#define RBMHEICHT 210 
#define RBMDEPTH SBMDEPTH 


#define VSPRITEWIDTH 1 /* My VSprite constants. */ 
#define VSPRITEHEIGCHT 12 

#define VSPRITEDEPTH 2 

#define NSPRITES 2 


#define BOBWIDTH 62 /* My Bob constants. */ 
#define BOBHEIGHT 31 

#define BOBDEPTH 4 

#define NBOBS 2 


struct IntuitionBase *IntuitionBase 
struct CfxBase *GfxBase = NULL; 


NULL; 


eo 


struct IntuiMessage *MyIntuiMessage = NULL; 


struct TextAttr TestFont = { /* Needed for opening screen. */ 
} (STRPTR) "topaz. font", TOPAZ_EICHTY, 0, 0 


/* DBL BUF */ 
struct BitMap *MyBitMapPtrs[2] = {NULL, NULL}; 
WORD ToggleFrame = 0; 


@ 


struct GelsiInfo GInfo; /* For all Gels. */ 


struct VSprite _veprd tes (NSERITES| 
WORDBITS VSpriteImage([] = { 

/* Piane 0, Plane l * 

OxEFEF, OxFFFF, /* Line l, first. */ 
OxEFFFF, 0xC003, 

OxFFFF, 0xC003, 

OxEFOOF, OxCFE3, 

OxFOOF, OxCFE3, 

OxFOOF, 0xCC33, 

OxFOOF, 0xCC33, 

OxFOOF, OxCFF3, 

OxFOOF, OxCFF3, 

OxFFEFF, 0xC003, 

OxFFFF, 0xC003, 

OxFEFF, OxFFEFF, /* Line 12, last. */ 


USHORT *VSpriteImage_chip = 0; 


/ 


17,18,19 
21,22, 23 
25, 26, 27 
29, 30,31 


MM Me Me HH He MH OM OM 
Mm 


sprite 
sprite 
sprite 
sprite 


WORD MyVSpriteColors [ 


0x0 £0Q, 


}: 


/* Fu 
Ox00f0, /* Full 
Ox000f /* Full 


struct Bob *Bobs [NBOBS] 


short Pon mage 
OxFFEE, 


0xC000, 
OxCFEFE, 
0xCC00, 
OxCCFE, 
0xCCCO, 
OxCCCE, 
0xCCCC 


OxF000, 
OxF000, 
OxFOFE, 
OxFOFFE, 
OxFOFO, 
OxFOFO, 
OxFOFO, 
OxFOEFO, 
OxFOFO, 
OxEFOFO, 
OxFOFO, 
OxEFOFO, 
OxFOFO, 
OxFOFO, 
OxFOFO, 
OxFOFO, 
OxFOFO, 
OxFOFO, 
OxFOFO, 
OxFOFO, 
OxFOFO, 
OxFOFO, 
OxFOFO, 
OxFOFE, 
OxFOFF, 
OxF000, 
OxF000, 
OxEFFFE, 
OxFEFE, 


OxEFFF, 
OxFEFE, 
OxFFFE, 
OxFEFE, 
OxFEOO, 
OxEFFOO, 
OxFEOO, 
OxFE00, 
OxFEOO, 
OxFEOO, 
OxFFOO, 
OxFFOO, 
OxFFOO, 
OxFEOO, 
QOxFEOO, 
OxFEF0O, 
OxFEOO, 
OxFFOO, 
OxFFOO, 
OxFFOO, 
OxFEOO, 
OxFFOO, 
OxFFOO, 
OxFFOO, 
OxFFOO, 
OxFEOO, 


OxFEFE, 
0x0000, 
OxFFEF, 
0x0000, 
OxFFEE, 
0x0000, 
OxFFEE, 
0x0000, 
OxFEFE, 
0xC000, 
OxCFEE, 
0xCC00, 


0x0000, 
0x0000, 
OxFFEFE, 
OxFFFE, 
0x0000, 


OxFOEFO, 
OxFOFO, 
OxFOFFE, 
OxFOFE, 
OxF000, 
OxF000, 
OxFFEF, 
OxFFFE, 
0x0000, 
0x0000, 
OxFEFE, 
OxFEFE, 
0x0000, 
0x0000, 
OxFEEFE, 
OxFFEF, 


OxEFFE, 
OxFFFE, 
OxFFFE, 
OxFFFE, 
0x0000, 
0x0000, 
0x0000, 
0x0000, 
OxFEFE, 
OxFFFE, 
OxEFFF, 
OxFFFE, 
OxFFOO, 
OxFFOO, 
OxEFOO, 
OxFFOO, 
OxFFO0, 
OxFFOO, 
OxFFOO, 
OxFEFE, 
OxFEFE, 
OxFFFE, 
OxFFEE, 
0x0000, 
0x0000, 
0x0000, 


Ve 


in sets of 
0 and 1, 
2 and 3, 
4 and 5, 
6 and 7. 
Please read the section on how VSprites are assigned in the RKM. 


a */ 


These are the colors that will be used for 
colors, not color register numbers. High to 
down to LSB, there are four bits each of red, green and blue. Please read the 


sprite section of the hardware manual. The gels system will put them into the 
proper color registers when th 
use color registers 


green. */ 


blue. */ 


OxFFEFE, 
0x0000, 
OxFFFE, 
0x0000, 
OxFFFE, 
0x0000, 
OxFFFE, 
0x0000, 
OxFFEC, 
0x000C, 


0x00CC, 


0x00CC, 


0x000C, 
OxFEEC, 


’ 0x0000, 


OxFFEF, 
0x0000, 
OxFFFE, 
0x0000, 
OxFFEF, 
0x0000, 
OxFFFE , 


OxFFFE, 
OxEFFE, 


0x0000, 
0x0000, 
OxFFFE, 
OxFFFE, 
0x0000, 
0x0000, 
OxFEFEC, 
OxEFFEC, 
0x003C, 
0x003C, 


0x0000, 


OxFEEC, 
0x000C, 
OxFECC, 
0x00CC, 


0x0CCC, 


0x0CCC 


OxFEEC, 
OxFFEC, 


0x003C, 
0x003C, 
OxFC3C, 
OxEC3C, 
0x3C3C, 
0x3C3C, 
0x3C3C, 
0x3C3C, 
0x3C3C, 
0x3C3C, 
0x3C3C, 
0x3C3C, 
0x3C3C, 
0x3C3C, 
0x3C3C, 
0x3C3C, 
0x3C3C, 
0x3C3C, 
0x3C3C, 
0x3C3C, 
0x3C3IC, 
0x3C3C, 
0x3C3C, 
OxEC3C, 
OxFC3C, 
0x003C, 
0x003C, 
OxFFEC, 
OxEFEFEC, 


OxFEEC, 
OxFEFEC, 
OxFFEC, 
OxFFFC, 
0x03EC, 
0x03EC, 
0x03EC, 
0x03EC, 
Ox03EC, 
0x03EC, 
0x03EC, 
0x03EC, 
0x0 3EC, 
0x03EC, 
0x03EC, 
0x03EC, 
0x03FC, 
Oxo are 
Ox03EC, 
0x03EC, 
0x03EC, 
0x03EFC, 
0x03EC, 
0x03EC, 
0x03EC, 
0x0 3EC, 


/* Plane 0, 


/* Plane 0, 
/* Plane 1, 


/* Plane 1, line 31. */ 
line 1. 


/* Piane 2, 


line 1. 


line 31. */ 
line 1. 


ae 


a7 


*/ 


VSprites. Note I really do mean 
ow, starting at bit 12 and going 


“Y are displayed. Reminder: Sprites can only 
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OxFE00, 0x0000, 0x0000, Ox03EC, 
OxFEFE, OxFFFE, OxEFFFE, OxFFEC, 
OxFFFE, OxFFFE, OxFFFE, OxEFFEC, 
OxFEFE, OxFFEF, OxFEFE, OxFFEC, 
OxFFEE, OxFFFF, OxFFEF, OxFFFC, /* Plane 2, line 31. */ 


OxFFFF, OxFFEF, OxFFFF, OxFFFC, /* Plane 3, line 1. */ 
OxFEFE, OxFFEFF, OxFEFEFE, OxEFEC, 

OxFEFE, OxFEEE, OxFEFE, OxFFEC, 

OxFFFE, OxFEFF, OxEFEFE, OxFEEC 
OxFFFE, OxFFEE, OxEFEF, OxFEEFC, 
OxEFEFF, OxFFFE, OxEFFE, OxFEEC, 
OxFFFE, OxFEFF, OxFFFF, OxFFEC, 
OxFFFE, OxFFFE, OxEFFEF, OxFFFC, 
OxFFFE, 0x0000, 0x0003, OxFEFC, 
OxFFFE, 0x0000, 0x0003, OxFFEC, 
OxFFFE, 0x0000, 0x0003, OxFFEC 
OxFEFE, 0x0000, 0x0003, OxEFEC 
OxFFEFF, 0x0000, 0x0003, OxFFEC, 

OxFFFE, 0x0000, 0x0003, OxFFEC, 

OxFEFE, 0x0000, 0x0003, OxFFEC, 

OxFFEEF, 0x0000, 0x0003, OxEFEC, 

OxFEFFE, 0x0000, 0x0003, OxFFEC, 

OxFFFE, 0x0000, 0x0003, OxEFFEC, 

OxFFFE, 0x0000, 0x0003, OxFFEC, 

OxFEFE, 0x0000, 0x0003, OxFEFC, 

OxFFFE, 0x0000, 0x0003, OxFFEC, 

OxFEFF, 0x0000, 0x0003, OxEFFEC, 

OxEFFFE, 0x0000, 0x0003, OxFEFEC, 

OxFFFE, OxFFFE, OxEFFEF, OxEFEC, 

OxFFFE, OxFEFFE, OxEFFF, OxFEFC, 

OxFFFE, OxEFFEF, OxFFEF, OxEFEC, 

OxFFFE, OxFFFF, OxEFFF, OxEFEFC, 

OxFFFF, OxFFFE, OxEFEF, OxFEFC, 

OxFFFE, OxFFFE, OxEFEF, OxFFFC, 

OxFFFE, OxFEFF, OxEFFFE, OxFEFC, 

OxFFFE, OxFFFE, OxEFEF, OxFEFC /* Plane 3, line 31. */ 


SsHoRT *BobImage_chip = 0; 


/* These are for wy custom screen. */ 
struct Screen *screen = 


, 


struct NewScreen ns = { 
0, 0, /* Start position. */ 
SBMWIDTH, SBMHEICHT, SBMDEPTH, /* Width, height, q th. */ 
0, 0, /* Default detail pen, block pen. 
NULL, /* Viewing mode. * 
CUSTOMSCREEN | CUSTOMBITMAP , /* Screen type. DBL BUF */ 
&TestFont, /* Font to use. * 
NULL, /* No default title. */ 
NULL, /* No pointer to additional gadgets. a/ 
NULL /* No pointer to CustomBitMap. 


}: 


/* These are for my window. */ 
struct Window *window = NULL; 


qe 


struct NewWindow nw = { 
52.05 /* Start position. */ 
SBMWIDTH, SBMHEIGHT, Me Width, each gh oa 
° 


0, 0, Detail 

CLOSEWINDOW, * IDCMP flags. */ 

WINDOWCLOSE | BORDERLESS, jr Flags 

NULL, /* No pointer to (eget *( 
NULL, /* No pointer to first CheckMar */ 
NULL, /* No default Title. */ 

NULL, /* No pointer to Screen. */ 

Nae /* No aa to BitMap. */ 

0, 0, /* MinWidth MinHeight inot used). */ 


SBMWIDTH, SBMHEIGHT, /* MaxWidth, Macdiet ght not used). */ 
CUSTOMSCREEN /* Screen type. 


}: 


BGA IG IIIS IGIOI SII TIOCIGIOIOIIR TOTES AIT ISIS ATI IAAI AIA 
* This will be called if a sprite collision with the border is detected. 
nh 


borderPatrol (s, b) 
struct VSprite *s; 
co b; 
register struct vinfo *info; 


info = &s->VUserExt; 


if (b & (TOPHIT | BOTTOMHIT) ) /* Top/Bottom hit, change direction. */ 
info- ies rf ne ae 

if (b & (LEETHIT | RI IT)) /* Left/Right hit, change direction. */ 
info->vx = - (info->vx) ; 


2 
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* Fun Starts. 
x 


main () 
SHORT 1, j; 


/* Open libraries that will be used directly */ 


if IY Geen inraret = (struct TntuitionBase 4) 
ibrary (“intuition. libra Y_VERSION)) == 0 
#ifdef pEBuc “ )) )¢ 
kprintf("Main: Can't open Intuition.\n”) ; 
#endif 0: 
MyCleanup 
Exit (-1); 


if ((GfxBase = (struct CfxBase *) 


nLibrary raphics.libra , LIBRARY_VERSION == 0 
#ifdef DEBUG FAP Zs )) »¢ 


kprintf("Main: Can't open Graphics.\n"); 


#endif 
MyCleanup () ; 
Exit (-1); 


JG EISSIISISISISIOIIGISIOISIEIDITISIISISIDISISISIISICISISIOISISIIISICIIIDITIDISIISIOIDI IDSC IDI SIDIGIDISIDISISIDIOIDI IOI II IOI I II IT 
: DBL BUF 
for (j=0; jf<2; j++) { 
if Ay Bi Mepe cre Ly) = (struct BitMap . 

llocMem (sizeof (struct BitMap), —CHIP)) 

#ifdef DEBUG 
kprintf("Main: Can't allocate BitMap.\n") ; 

#endif 


ersten 0. 


== 0) { 


ee ah eye pete el ]. RBMDEPTH, RBMWIDTH, RBMHEIGHT) ; 
for (i4=0; i<RBMDEPTH; i++ 


if BitMapPtrs ->Planes [i] = (PLANEPTR)AllocRaster (RBMWIDTH, 
C(teye seater eve ld- eNansellt) Si ) ® 
#ifdef DEBUG 

kprintf("Main: Can't allocate BitMaps' Planes.\n") ;: 
#endif 


acc 


1tClear (MyBitMapPtrs([j]->Planes(i], (RBMWIDTH / 8) * RBMHEIGHT, 1); 


ns .CustomBitMap = pias epee) /* tt */ 
screen->RastPort.Flags = DBUFFER; 


/* Open My Very Own Screen. * 


if ((screen = (struct Screen 4) OpenScreen (éns)) == 0) { 
#ifdef DEBUG | 


kprintf ("Main: Can't open Screen.\n") ; 


#endi f ( 
MyCleanup () ; 
Exit (-1); 
‘ /* Now get that flashing title bar off the display. DBL BUF */ 
/ 
screen->ViewPort .RasInfo->RxO0ffset = 5; 
‘ screen->ViewPort .RasInfo->RyOffset = 5; 
/ 


/* Set screens’ colors (Could've used LoadRGB4()). */ 
SetRGB4 (&screen->ViewPort, 00, 00, 00, 00); 

SetRGB4 (&screen->ViewPort, 01, 15, 00, 00); 
SetRGB4 (&screen->ViewPort, 02, 00, 15, 00); 
SetRGB4 (&screen->ViewPort, 03, 00, 00, 15); 
SetRGB4 (&screen->ViewPort, 04, 15, 15, 00); 
SetRGB4 (&screen->ViewPort, 05, 15, 00, 15); 
SetRGB4 (&4screen->ViewPort, 06, 08, 15, 15); 


SetRGB4 (&screen->ViewPort, 07, 15, 11, 00 
SetRGB4 (Sscreen->ViewPort, 08, 05, 13, 00 
SetRGB4 (&screen->ViewPort, 09, 14, 03, 00 
SetRGB4 (&screen->ViewPort, 10, 15, 02, 14 
SetRCB4 (&4screen->ViewPort, 11, 15, 13, 11 
SetRGB4 (&4screen->ViewPort, 12, 12, 09, 08 
SetRGB4 (&screen->ViewPort, 13, 11, 11, 11 
SetRGB4 (&4screen->ViewPort, 14, 07, 13, 15 
SetRCB4 (4screen->ViewPort, 15, 15, 15, 15 


Be Vo Vea Ve Ve Ba Be Ye Bo 


nw.Screen = screen; 


if ((window = (struct Window *) OpenWindow(4nw)) == 0) { 
#ifdef DEBUG 
kprintf ("Main: Can't open Window.\n") ; 
#endif 


mrcueenye 0 


[BRR EREREREREEER MEEKER ERA REE AREER ERR ER EKER EER ER ARERR EERE REE IRIE 


* Now that the screen envirionment is set up, It's time to set up the 
: gels systen. 
/ 


/* ReadyGels is in CelTools(). */ 
if Raacyceta (sGrn te: &screen->RastPort) != 0) { 
#ifdef DEBU 
kprintf("Main: ReadyGels failed.\n”") ; 
#endif 


rn 


SetCollision(0, borderPatrol, &GInfo) ; 


/* Co Images to chip memory. */ 
if (iInitImages()) { 
#ifdef DEBUG 


kprintf(“Main: InitImages() failed.\n"); 
#endif 


1 ; 
tee 


DRS GIGGIG ISIS ISIDIGIGISI I SIDIGISIOIGITIOITIGIIGICIOI TOIT TOT GEIS SOO IAAI AIA 
* System is set up, now set up each Cel. 
aA 


/* First use the routines in geltools to get the sprite. */ 
for(i = 0; i < NSPRITES; i++) 
if CWSprttes i] = (struct VSprite *)MakeVSprite (VSPRITEHEICHT, 
VSpriteImage_chip, &MyVS peers LY , 1*6, (1*8)+10, 
VSPRITEWIDTH, VSPRITEDEPTH, VSPRITE)) == 0) 
#ifdef DEBUG 7 1 
kprintf("Main: MakeVSprite failed.\n") ; Animation 181 


#endif 


MyCleanup () ; 

Exit (-1); 
VSprites [i] ->VUserExt.vx = 1; 
VSprites (ij->VUserExt.vy = 1; 
VSprites [i] ->VUserExt.id = i; 


AddVSprite(VSprites [i], &screen->RastPort) ; 
} 


/* First use the routines in geltools to get the bob. */ 
for(i = 0; i < NBOBS ; i++) 
if ( (Bobs ij = (struct Bob *)MakeBob yey. BOBHEIGHT, BOBDEPTH, 
Bob nage eee kOe ee coS i*6), (i*8) +10, 
SAVEBACK | OVERLAY)) = 
#ifdef DEBUG 
kprintf("Main: MakeBob Tad a 
#endif 


piece 


~>BobVSprite->VUserExt .vx 
->BobVSprite->VUserExt .vy 
->BobVSprite->VUserExt .id 


Bobs |i 
i 


/* DBL BUE */ 
if (bobs a). “spBut ter = SESCaIEN) ta a aaa *)AllocMem (sizeof (struct 


acket) , IP)) 
#ifdef DEBUG 
kprintf("Main: Can't allocate double buffers’ packet for a bob.\n"); 
#endif 


eee 


te (Bere OB peer eT cee a sccn ae LEO Mca ee * 
BWIDTH+15S) /16) * BOBHEI * BOBDEPTH, MEME_CHIP) ) { 
#ifdef pEsuc! 


Bobs [i 





be js 
» 


Bobs 


kprintf("Main: Can't allocate double buffer for a bob.\n"); 
#endi f 0: 
MyCleanup 
Exit (-1); 
dBob (Bobs [i], &screen->RastPort) ; 
/* The ee relies on the fact that AddBob sets the before 
* and after nters to 0, so the first before and last after. 
* are left alone. 
* Earlier bob has higher priority, thus this bob'll be drawn 
* AFTER that one, thus this bob will appear on top of all earlier 
* ones. One could set the bobs to be drawn in any order by rearranging 
* these pointers. 
*/ 


if (i > 0) 


Bobs {(i]->After = Bobs [i-1]; 
Bobs {|i|->After->Before = Bobs [i]; 


} . End of for. */ 


DRG IGG ISI IIIS IGT TAS AIA IA II IO IAI IIA IIIA I III IA 
: Hey, wow, everything opened, and allocated, and initialized! Whew. 


tor (3 t5(); 


while dotvagiwiniowes = (struct IntuiMessage *) 
(window->UserPort) ) 
switch (tyIntuiMessage- >Class) { 
case CLOSEWINDOW: 

ReplyMsg ( poe nares 

BYTE aR 

Exit (TRUE) ; 

break; 


} 


FOO OOO IOI GIGI IOI IOI IOI OISIOISIUIGIOI II IGISIGIOI OI IOI IOI OIC III OIG OT ITOK 
* DrawGels part of loop. 
oe 


reine 
register struct VSprite *pSprite; 


/* Move everything in the sprite list. This includes Bobs. */ 

pSprite = Ginfo.gelHead->NextVSprite; 

while (pSprite != CInfo. gelTaii} { 
pSprite->X += pSprite->VUserExt .vx; 
pSprite->Y += pSprite->VUserExt .vy; 
pSprite = pSprite->NextVSprite; 


SortGList (&screen->RastPort) ; /* Put the list in order. */ 

DoCollision (&screen- >RastPort) ; /* Collision routines il called now. */ 
DrawGList (&screen->RastPort, &screen- >ViewPort) ; /* Draw oe 
screen->ViewPort .RasInfo->BitMap = MyBitMapPtrs (ToggleFrane] ; /* DBL BUF */ 
WaitTOF () ; /* When the beam hits the top... */ 
MakeScreen (screen) ; /* Tell intuition to do it's stuff. xy 
RethinkDisplay () ; /* Does a MrgCop & LoadView. */ 
ToggleFrame “=1; 


; /* DBL BUE */ 
} screen->RastPort .BitMap = MyBitMapPtrs [ToggleFrame] ; /* DBL BUF */ 


[DO IUIOIGISICICICITIGISINIDISIGOIOIGICIGIOIIGI OIC OICICICISIOIOIDIOIDIGIGIGIGISIDISISISISIDIDIOIICISIGISI IOI GIO GISI III SIDI II I 
9 ‘ ‘ * This will be called in case of error, or when main is done. 
182 Animation + / 


MyCleanup () 
short i, j: 


for 7 0; i < NBOBS; i++) { 
(Bobs (1) 1= L { 
Delet (Bobs [i] ->BobVSprite) ; 


} 
for it =0; i< Sti} t= ih i++) { 
(VSprites (4) != NULL 
DeleteGel (VSprites [i] 


hircetais (&GIn fo) ; 

Freel mages () ; 

if (window 1= NULL 
{onenindow Window); 

if Apcreen 1= 
topederoan Gcreen\: 


/* DBL BUE ee 


fore 
ten Joe != NULL 
aa ern 
if MyBitMapPtrs [1 ]->Planes i] != 0) 
reeRaster (MyBitMapPtrs [j]->Planes [i], RBMWIDTH, RBMHEIGHT) ; 


+ reeMem (MyBitMapPtre [J]. sizeof (struct BitMap)) ; 


} 


if (CfxBase != NULL 


loseLibrary (Gf. ane) 5 
if (IntuitionBase != 


} ieee sbrary (EAtuielenbaaey: 


foe 


extern USHORT Bete eee ae 
extern USHORT *BobImage_chip; 
int i; 


if (Spr Atelmage__ chip = (USHORT * 
cMen (sizeof (VSpriteImage), MEMF_CHIP)) == 0) { 
#ifdef DEBUG 


PErAnee ( iateimages: No Memory for VSpriteImage.\n”") ; 
#endi f 
return (FALSE) ; 


if ((BobImage_chip = (USHORT * 
AllocMenm (sizeof (BobImage), MEMF_CHIP)) == 0) { 
#ifdef DEBUG 


rintf("InitImages: No Memo for BobImage.\n") ; 
‘ ce? ( g ry g ) 
return (FALSE) ; 


for (1=0; 1<24; i++) 

Spritermage.ch vent [1] = VSpriteImage [i]; 
for (1=0; 1<49 

obImage_: chip[i} = BobImage [i]; 
return (TRUE) ; 


pet 


extern USHORT eect ace ecto 
extern USHORT *BobImage_chip; 


if (Weer tt elmage. chip != 0) 

fesse en Le chip, sizeof (VSpriteImage) ) ; 
if (Bop inage. chip. | 

FreeMem (Bo peace. chip, sizeof (BobImage) ) ; 
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eee Hee HHH HD DH 


#include 
#include 
#include 


intuall.h, general includer for intuition 


Confidential Information: Commodore-Amiga, Inc. 
Copyright (c) Commodore-Amiga, Inc. 


Modification History 


1-30-85 -=RJ=- cre 


<exec/types .h> 
<exec/nodes .h> 
<exec/lists .h> 


/* #include <exec/interrupts.h> */ 


#include 
#include 
#include 
#include 
#include 
#include 
#include 


#include 
#include 
#include 
#include 


<exec/menory .h> 
<exec/ports .h> 
<exec/tasks .h> 
<exec/libraries .h> 
<exec/devices .h> 
<exec/io.h> 

<exec /devices .h> 


<devices/console.h> 
<devices/timer .h> 
<devices /keymap .h> 
<devices /inputevent .h> 


#define Msg IOStdReq /* 


#include 
#include 


#include 
#include 
#include 


<libraries/dos .h> 
<libraries/dosextens .h> 


<graphics/gfx.h> /* 
ede / 
<hardware/blit .h> 


* 


#define blitNode bltnode /* 


#include 
#include 
#include 
#include 


#include 
#include 
#include 


<graphics/collide.h> 
<graphics/copper .h> 
oer ce ee 
<hnardware/dmabits .h> 
<graphics/gels .h> 
<graphics/clip.h> 
<graphics/rastport .h> 
<graphics/view .h> 
<graphics/gfxbase .h> 
<graphics/text .h> 


/* #include <hardware/intbits.h> */ 


#include 
#include 
#include 
#include 
#include 


<hardware/custom .h> 
ee ee eon 
<graphics/layers .h> 
<intuition/intuition .h> 
<devices/gameport .h> 


date author : Comments 


ated this file! 


HAKKAR EE RAR REREEK ER RR REAR REE KERR RRR AERKREERR EERE RRR EEE A ERE EEK RARER EERE / 


temporary kluge for dosextens.h */ 


ALWAYS INCLUDE GEX.H before other includes */ 
new as of 7/9/85 */ 


temporary kludge for gels.h */ 


/* changed so I can get gadget addr */ 


GELTOOLS.C - 


A FILE CONTAINING USEFUL SETUP TOOLS FOR THE ANIMATION SYSTEM 


author: Rob Peck, incorporating valuable comments and changes from 
Barry Whitebook and David Lucas. 


#include <exec/types .h> 

#include <exec/menory .h> 

#include <graphics/gfx.h> /* ALWAYS INCLUDE GEX.H before other includes */ 
#include <graphics/gels.h> 

#include <graphics/clip.h> 

#include <graphics/rastport .h> 

#include <graphics/view.h> 

#include <graphics/gfxbase .h> 


[BERR ERERAR ERR EAR ARERR AREA EERIE RAR IKRAR EAR TE REET REAR KREE IKE AE EKER RENTER TER 


* This file is a collection of tools which are used with the vsprite and 
bob software. It contains the following: 


ReadyGels( *gelsinfo, *rastport ); 
PurgeGels( *gelsinfo ); 


struct VSprite *MakeVSprite (lineheight, *image, *colorset,x,y, 
wordwidth, imagedepth, flags) ; 
DeleteVSprite( &VSprite ) ; 


struct Bob *MakeBob (bitwidth, lineheight, imagedepth, *image, 
planePick, planeOnOff,x,y) 
DeleteBob( &Bob ); 


Rea ls sets up the defaults of the gel stem by initializing the 
Gelsinfo structure you provide. Firat it allocates room for and 
links in lastcolor and nextline. It then uses information in your 
RastPort structure to establish boundary collision defaults at 

the outer edges of the raster. It then links together the GelsInfo 
and the RastPort which you provide. Next it allocates space for two 
dummy virtual sprite structures, calls InitCels and SetCollision. 
You must already have run LoadView before ReadyGels is called. 


PurgeGels deallocates all memory which ReadyGels and NewGelList have 
allocated. The system will crash if you have not used these 
routines to allocate the space (you cant deallocate something 

which you havent allocated in the first place). 


cecueles allocates enough space for and inits a normal vsprite. 
DeleteVSprite deallocates the memory it used. 


MakeBob initializes a standard bob and allocates as much memory as is needed 
for a normal bob and its vsprite structure, links them together. 


To find the associated vsprite, look at the back-pointer (see the 
routine doc itself). 


DeleteBob deallocates the memory it used. 
Written by Rob Peck, with thanks to Barry Whitebrook and David Lucas. 


* 
* 
* 
* 
* 
* 
* 
* 
* 
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* 
x 
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void border_dumny () 


return; 


/* Caller passes a pointer to his GelsInfo structure which he wants to init, 
* along with a pointer to his IVPArgs. Default init places the topmost 
* bottommost etc at the outermost boundaries of callers rastport parameters. 
* Caller can change all this stuff after this routine returns. 
*/ 


extern struct RastPort *myRast; 


struct VSprite *SpriteHead 


NULL ; 
struct VSprite *SpriteTail 


NULL; 


[ BRRRRRERHEERER EERE ERERR EEE ERR EERE REE KERR ER REE KER IK A EEE RARER EEEEEREREEREEEEEEE 


* This routine cannot be run until the first LoadView (&view) has been 


* executed. InitGels works with an already active View, so LoadView 
must have been run first. 
/ 


ReadyGels(g, r) 
struct RastPort *r; 
struct CelsInfo *g; 


/* Allocate head and tail of list. */ 
if ((SpriteHead = (struct VSprite *)AllocMem (sizeof 
(struct VSprite), MEMF_PUBLIC | MEMF_CLEAR)) == 0) { 

#ifdef DEBUG 


kprintf ("ReadyGels: No memory for sprite head.\n") ; 
#endif 
return (-1); 


if ((SpriteTail = (struct VSprite *)AllocMem (sizeof 
struct VSprite), MEMF_PUBLIC | MEMF_CLEAR)) == 0) { 
#ifdef DEBUG 


kprintf ("ReadyGels: No memory for sprite tail.\n”) ; 
#endi f 
return (-1); 


/* By setting all bits here, it means that there are NO 
* reserved sprites. The system can freely use all of the 
* hardware sprites for its own Purposes: The caller will not be 
: trying to independently use any hardware sprites! 


g->saprRsrvd = -1; 


* The nextline array is used to hold stem information about 
z "t 
* "at which line number on the screen is this hardware sprite 


* aan going to become available to be given a new vsprite to 
* display”. 
/ 


if ((g->nextLine = *)AllocMem (sizeof * 8, 
(¢ MEMF _PUBLIC 1 GENE CLEAR) ) oe ore) pe 
#ifdef DEBUG 
kprintf ("ReadyGels: No memory for nextline.\n”") ; 


#endi f 
return (-1) ; 


In the lastcolor pointer array, the system will store 
a pointer to the color definitions most recently used 
by the system. .... as a reminder, virtual sprites can 
be assigned to any of the real hardware sprites which 
may be available at the time. The vsprite colors will 
be written into the hardware eeccre register set for 
the hardware sprite to which that veprite is assigned. 
This pointer array contains one pointer to the last 


set of three colors (from the vsprite structure ‘*saprColors) 
for each hardware sprite. 


As the system is scanning to determine which hardware 

pe should next be used to represent a vsprite, it 
ecks the contents of this array. If a hardware sprite 

is available and already has been assigned this set of 

colors, no color assignment is needed, and therefore 

no color change instructions will be generated for the 

copper list. 


If all vsprites use a different set of sprColors, (pointers 
to sprColors are different for all vsprites), then there 

is a limit of 4 vsprites on a horizontal line. If, on 

the other eer define, lets wae | 8 vsprites, with 

1 and 2 having the same sprColors, and 4 the same as 

each other, 5 and 6 the same as each other, and 7 and 8 
also having the same vsprite colors, then you will be 

able to have all 8 vsprites on the same horizontal line. 


In this case, you will be able to put all 8 vsprites on 

the same horizontal line. The reason this helps is that 
the system hardware shares the color registers between pairs 
of hardware sprites. The system thus has enough resources 
to assign all vsprites to hardware sprites in that there 


are 4 color-sets for 8 vsprites, exactly matching the 
hardware maximum capabilities. 


% 4 OO OO OO 
™ 


Note that lastcolor will not be used for bobs. Just sprites. 


if ((g->lastColor = ee hn oe * 8, 
MEMF_PUBLIC | MEME_CLEAR)) == NULL) { 
#ifdef DEBUG 


kprintf ("ReadyGels: No memory for lastcolor.\n") ; 
#endif 


return (-1) ; 


/* This is a table of pointers to the routines which should 
186 Animation * be performed when DoCollision senses a collision. This 


* declaration may not be necessary for a basic vsprite with 
* no collision corec ton implemented, but then it makes for 
: a complete example. 


if ((g->collHandler = (struct collTable * OLE 
collTable), MEMF_PUBLIC | MEME_: ») = { 
#ifdef DEBUG 
kprintf ("ReadyCGels: No memory for collHandler.\n"); 
#endi f 
return (-1); 


* When any part of the object touches or passes across 
* this boundary, it will cause the bounda collision 
* routine to be called. This is at smash [0] in the 

: collision handler table and is called only if 


c DoCollision is called. 


g->leftmost = 0; 

g->rightmost = = r->BitMap->BytesPerRow * 8 - 1; 
g->topmost = 0; 

g->bottommost = r->BitMap->Rows - 1; 


r->GelsInfo = g; /* Link together the two structures */ 
InitGels (SpriteHead, SpriteTail, g ); 


/* Pointers initialized to the dummy sprites which will be 
used by the system to keep track of the animation systen. 


SetCollision 0, border_dummy, g 
WaitTOEF (); ( ue 
return (0) ; 


} 


[RRR RRR IIIT RRO I IIIT IK 


* Use this to get rid of the gels stuff when it is not needed any more. 
* You must have allocated the gels info stuff (use the ReadyGels routine). 
*/ 


Por gece (9? 
oo Gelsinfo *g; 


if (g->collHandler != NULL) 

reeMen (g->collHandler, sizeof (struct collTable)) ; 
if os lor != NULL 

->lastColor, sizeof(LONG) * 8); 

if ce eeneke ine != NULL 

reeMem (g->nextLine, sizeof (WORD) * 8); 
if £3, >gelHead != NULL 

peeton(s, Arpad sizeof (struct VSprite)); 
if {3 >gelTail 
} reeMen (g- soeitsil, sizeof (struct VSprite) ) ; 


[BERR REH KERR AER ER ERK ERR IR ERI RARER IIR IRR AIRE ITAA RIT AAAI AER IITA RITA 


* Because MakeVSprite is called by MakeBob, MakeVSprite only creates the 
* VSprite,it doesn't add it to the system list. The calling routine must 
oe an AddVSprite after it is created. 


struct VSprite *MakeVSprite(lineheight, image, colorset, x, ¥’ 
s 


wordwidth, imagedepth, flag 
SHORT lineheight; /* How tall is this vsprite? */ 
WORD *image; /* Where is the vsprite image data, should be 
twice as many words as the value of lineheight */ 
WORD *colorset; /* Where is the set of three words which describes 
the colors that this vsprite can take on? */ 
SHORT x, y; /* What is its initial onscreen position? */ 


SHORT wordwidth, imagedepth, flags; 


struct VSprite *v; /* Make a pointer to the vsprite structure which 
this routine dynamically allocates */ 


if ((v = (struct VSprite mye ey VSprite), 
( MEME PUB CIC | MEME_CLEAR)) = == 0) { 
#ifdef DEBUG 


printf ("MakeVSprite: Couldn't allocate VSprite.\n") ; 
#endi ft 


return (0) ; 


v->Flags = flags; /* Ie this a vsprite, not a bob? */ 


v->Y 
v->X 


yy: /* Establish initial position relative to */ 
x; /* the Display coordinates. */ 


v->Height = lineheight; /* The Caller says how high it is. */ 

v->Width = wordwidth; /* A vseprite is always 1 word (16 bits) wide. */ 

/* There are two kinds of depth... the depth of the ge itself, and the 

depth of the playfield into which it will be drawn a a depth 

says how much data space will be needed to store an image if it's 

2 Gpremegue 4 allocated. The playfield oc establishes Row much space 
11 be needed to save and restore the ackgr ound when a bob is drawn. 


A vsprite is always 2 Peenes deep, but if it's being used to make a 
bob, rat may be deeper.. 


/ 
v->Depth = imagedepth; 


+ He eM 


* Assume that the caller at least has a default boundary collision 
* routine.... bit 1 of this mask is reserved for boundary collision 
* detect during DoCollision(). The only collisions reported will be 
; with the borders. The caller can change all this later. 


v->MeMask = 1; 
v->HitMask = 1; 


v->ImageData = image; /* Caller says where to find the image. */ 
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/* Show system where to find a mask which is a squished down version 
* of the vsprite (allows for fast horizontal border collision detect). 


ae 
if v->BorderLine = (WORD aoe sizeof RD) *wordwidth 
CN eee MEME EdRY) {( (WORD) ). 


UBLIC | 
#ifdef DEBUG 
Oetne Fists Vasnicet: Couldn't allocate BorderLine.\n”") ; 
#endi f 
return (0) ; 


/* Show system where to find the mask which contains a 1 bit for 
* position in the object in any plane where there is a 1 bit (all planes 
: OR ‘ed together) . 
7 


if Mee GHP | = ( WORD EE) ae ee 


ME_CHIP 
#ifdef DEBUG 
[DEBUG savgprite: Couldn't allocate CollMask.\n") ; 
#endif 
return (0) ; 


/* This isn't used for a Bob, just a VSprite. It’s where the 
* Caller says where to find the VSprites colors. 
x 


v->SprColors = colorset; 


/* These aren't used for a VSprite, and MakeBob'll do set up for Bob. */ 
v->PlanePick = 0x00; 
v->PlaneOnOff = 0x00; 


InitMasks (v) ; /* Create the collMask and borderLine */ 
return (v) ; 


} 


struct Bob *MakeBob (bitwidth, lineheight, imagedepth, image, 

Proneen | ,planeOnOff, x,y, flags 
SHORT bitwidth, lineheight, imagedepth, planePick, planeOnOff,x,y, flags; 
WORD *image; 


struct Bob *b; 
struct VSprite *v; 
SHORT wordwidth; 


wordwidth = (bitwidth+15) /16; 


/* Create a vsprite for this bob, it will need to be deallocated 
* later jiree) when this bob gets deleted. 
: Note: No color set for bobs. 


/ 

if ((v = Maloy -pra ce (LAnshetgne, image, NULL, x, y, wordwidth, 
imagedepth, flags) 0) { 

#ifdef DEBUG 


kprintf ("MakeBob: MakeVSprite failed.\n") ; 
#endi f 
return (0) ; 


/* Caller selects which bit planes into which the image is drawn. */ 
v->PlanePick = planePick; 


/* What happens to the bit planes into which the image is not drawn. */ 
v->PlaneOnOff = planeOnOff; 


if ((b = (struct Bob ele CLEAR)) 20) Bob) , 
PUBLIC | MEME_CLEAR) ) 0) { 
#ifdef DEBUG 


a ae Couldn't allocate bob.\n") ; 
#endi f 


return (0) ; 


v->VSBob = b; /* Link together the bob and its vsprite structures */ 


b->Flags = 0; /* Not part of an animation (BOBISCOMP) and don't keep the 
image present after bob is removed (SAVEBOB) */ 


/* Tell where to save Poa Must have enough space for as many 
bitplanes deep as the display into which everything is being drawn. 
/ 


if ((b->SaveBuffer = (WORD *)AllocMem(sizeof (SHORT) * wordwidth 
* lineheight * imagedepth, MEMF_CHIP | MEMF_CLEAR)) == 0) { 
#ifdef DEBUG 
kprintf("“MakeBob: Couldn't allocate save buffer .\n") ; 
#endif 
return (0) ; 


b->ImageShadow = v->CollMask; 


/* Interbob priorities are set such that the earliest defined bobs have 
* the lowest priority, last bob defined is on top. 


ae 

b->Before = NULL; /* Let the caller worry about priority later. */ 
b->After = NULL; 

b->BobVSprite = v; 


/* InitMasks does not preset the imageShadow ... caller may elect to use 
* the collMask or to create his own version of a shadow, although it 


* is usually the same. 
we 


b->BobComp = NULL; /* this is not part of an animation */ 
b->DBuffer = NULL; /* this is not double buffered */ 


/* Return a pointer to this newly created bob for additional caller 


: interaction or for AddBob (b) ; 


return (b) ; 


/* Deallocate memory which has been allocated the routines Makes. */ 
* Assumes images and imageshadow deallocated elsewhere. */ 


leteGel (v) 
struct VSprite *v; 


if “ !1= NULL) { 
f (v->VSBob != NULL) { 
if (v->VSBob->SaveBuffer != NULL) { 
reeMem (v->VSBob- Se Destnh: sizeof (SHORT) * v->Width 


* v->Height * v->Depth 


f (v->VSBob->DBuffer != wet) { 
if (v->VSBob->DBuffer->BufBuffer != 9) -t 
reeMen (v->VSBob- >DBu ffer->Bu £Bu ffe 
sizeof (SHORT) * v->Width * v- SHeight * v->Depth) ; 


} 
i 


Fi eaea (v->VSBob->DBuffer, sizeof (struct DBu fPacket) ) ; 
reeMem( v->VSBob, sizeof (struct Bob)) ; 


} 
if (v->CollMask != NULL) { 
reeMem (v->CollMask, sizeof (WORD) * v->Height * v->Width) ; 


if (v->BorderLine != NULL) { 
reeMem (v->BorderLine, sizeof (WORD) * v->Width) ; 


reeMen(v, sizeof (struct VSprite)) ; 
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Chapter 4 


Text 


Introduction 


Text on the Amiga is simply another graphics primitive. Because of this, you can easily inter- 
mix text and graphics on the same screen. Typically, a 320-by-200 graphics screen can contain 
40-column, 25-line text using a text font defined in an 8-by-8 matrix. The same type of font 
can be used to display 80-column text if the screen resolution is extended to 640 by 200. Win- 
dow borders and other graphics embellishments may reduce the actual available area. 
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The text support routines use the RastPort structure to hold the variables that control the 
text drawing process. Therefore, any changes you make to RastPort variables affect both the 
drawing routines and the text routines. 


In addition to the basic fonts provided in the ROMs, you can link your own font into the sys- 
tem, and ask that it be used along with the other system fonts. 


This chapter shows you how to: 
o Print text into a drawing area 
o Specify the character color 
o Specify which font to use 
o Access disk-based fonts 
o Link in a new font 
o Define a new font 


o Define a disk-based font 


Printing Text into a Drawing Area 


The placement of text in the drawing area depends on several variables. Among these are the 
current position for drawing operations, the font width and height, and the placement of the 
font baseline within that height. 


CURSOR POSITION 


Text position and drawing position use the same variables in the RastPort structure—cp_y 
and cp_x, the current vertical and horizontal pen position. The text character begins at this 
point. You use the graphics call Move(&rastPort, x, y) to establish the ep_y and cp_x 
position. 
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BASELINE OF THE TEXT 


The cp_y position of the drawing pen specifies the position of the baseline of the text. In other 
words, all text printed into a RastPort using a single “write string’? command is positioned 
relative to this cp_y as the text baseline. Figure 4-1 shows some sample text that includes a 


character that has 1 dot below the baseline and a maximum of 7 dots above and including the 
baseline. 


For clarity, blank squares and shaded squares, rather than Os and ls, are used for the figure. 


Baseline for the 
character set 





Figure 4-1: Text Baseline 


The figure shows that for this font, the baseline value is 6. The baseline value is the number of 
lines from the top of the character to the baseline. 


When the text routines output a character to a RastPort, the leftmost edge of the character 
position is specified by the ep_x (current horizontal position) variable. 


After all characters have been written to the RastPort, the variable cp_y is unchanged. The 
value of cp_x will be changed by the number of horizontal positions that were needed to write 


all characters of the specified text. Both fixed-width and proportionally spaced character sets 
are accommodated. 


The default fonts in the system are all designed to be above and below the baseline, where the 
baseline position is at line 6 of the character font. This means that you must specify a cp_y 
value of at least 6 when you request that text be printed to a RastPort in order to assure that 
you stay within the memory bounds of the RastPort itself. Location (0,0) specifies the upper 
left-hand corner of the memory space that is dedicated to the RastPort. Because all text will 
be written above and below the baseline, you must start at a proper position or the routines will 
write into non-RastPort memory. 


You should not request that the text routines write beyond the outer bounds of the RastPort 
memory, either horizontally or vertically. Text written outside the RastPort bounds may be 
clipped if the RastPort supports clipping (most do). Clipping means that the system will 
display only that portion of the text that is written into the boundaries of the RastPort. 
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SIZE OF THE FONT 


Font design is covered later in this chapter. For now, simply note that the width and height of 
the font affect how many characters you may print on a line. The position of the baseline 
affects where you print a line. 


PRINTING THE TEXT 


You may print text into a RastPort by using the Text() routine. A typical call to this routine 
is: 


Text( &rastPort, string, count ) 


where 
&rastPort is a pointer that describes where the text is to be output 
string is the address of the string output 
count is the string length 


SAMPLE PRINT ROUTINE 


Here is an example showing a string to be written to a RastPort. This example assumes that 
you have already prepared a RastPort into which the text can be rendered. 


/* sample routine to print a single line of text to the screen. */ 
struct RastPort *rp; 
test( ) 


SetAPen(rp,1); = _/* use color number 1 to draw the text */ 
Move( rp, 0, 40); /* start down a few lines from the top */ 
Text( rp, ” This is test text”, 17 ); 

return(); 


} 
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Selecting the Font 


Character fonts each have a name. Two default character fonts are provided in the ROMs. 
One font produces either 40- or 80-column text (depending on the use of a 320 or 640 horizontal 
resolution, respectively). The other font produces either 32- or 64-column text. The names and 
specifications of these default fonts are are shown in table 4-1. 


Table 4-1: Default Character Fonts 


Font Type Height Name 
40/80 8 topaz.font 


32/64 9 topaz.font 


To specify which font the system should use, you call the system routine OpenFont() or 
OpenDiskFont(), followed by SetFont(). A typical call to these routines follows. 


font—OpenFont(textattr); 
font—OpenDiskFont(textattr); 
SetFont( font, rp ) 


where 


font 


is a pointer to a TextFont data structure, returned by either OpenFont() or 
OpenDiskFont(). 


textattr 
is a structure located in the include file graphics/text.h. It contains a pointer to a null- 


terminated string that specifies the name of the font, font height, font style bits, and 
font preference bits. 


rp is the address of the RastPort that is to use that font until told to use a different one. 


The call to OpenFont() or OpenDiskFont() says ‘“‘give me a font with these characteristics.” 
The system attempts to fulfill your request by providing the font whose characteristics best 
match your request. The table above shows that both of the system fonts have the name 
“topaz.font.’’ In the system font selections, the height of the characters distinguishes between 
them. If OpenFont() cannot be satisfied, it returns a 0. 
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Note: In chapter 1, ‘‘Graphics Primitives,” you saw that the routine InitRastPort() initializes 
certain variables to default values. This routine automatically sets the default to topaz.font 
with the correct width according to Preferences. 


The example below shows how a new font is selected. This example prints two lines of text to 
the screen, each line of text in a different font. It assumes that a RastPort is already set up 
elsewhere. 


#include ”graphics/text.h” 


test( ) 
{ 
struct TextAttr f; 
/* provide a font structure to build on for font change */ 
struct TextFont *font; 
f.ta_Name = ”topaz.font”; 
/* set font name into font descriptor struct */ 
/* initial font default is ‘“‘topaz.font”’ */ 
f.ta_YSize = 8; 
/* define font size * / 
f.ta_Style = 0; 
/* define font style */ 
f.ta_Flags = 0; 
/* define font preferences * / 
font—OpenFont(&f); 
if (font !=0) { 
SetFont( rp, font); 
/* ask system to find & set one like this */ 
Move( rp, 0, 40); 
Text( rp, ’topaz.font, 8 dots high”, 23 ); 
CloseFont(font); 
} 
f.ta_Ysize=9; 
font=OpenFont(&f); 
if (font != 0) { 
SetFont(rp,font); 
Move( rp, 0, 48); 
/* start a few lines down from the top */ 
Text( rp, *topaz.font, 9 dots high”, 23); 
CloseFont(font); 


return(0); 


} 


196 Text 


Selecting the Text Color 


You can select which color to use for the text you print by using the graphics calls SetAPen() 
and SetBPen() and by selecting the drawing mode in your RastPort structure. The combina- 
tion of those values determines exactly how the text will be printed. 


Selecting a Drawing Mode 


The DrawMode variable of a RastPort determines how the text will be combined with the 
graphics in the destination area. 


Note: The DrawMode selections are values, not bits. You can select from any one of the fol- 
lowing drawing modes. 


If DrawMode is JAM1, it means that the text will be drawn in the color of FgPen (the fore- 
ground, or primary, drawing pen). Wherever there is a 1-bit in the text pattern, the FgPen 
color will overwrite the data present at the text position in the RastPort. This is called over- 
strike mode. 


If DrawMode is JAM2, it means that the FgPen color will be used for the text, and the 
BgPen color (the background or secondary drawing color pen) will be used as the background 
color for the text. The rectangle of data bits that defines the text-character completely overlays 
the destination area in your RastPort. Where there is a 1 bit in the character pattern 
definition, the FgPen color is used. Where there is a O bit in the pattern, the BgPen color is 
used. This mode draws text with a colored background. 


If DrawMode is COMPLEMENT, it means that wherever the text character is drawn, a posi- 
tion occupied by a 1 bit causes bits in the destination RastPort to be changed as follows (see 


also figure 4-2): 


o If a text-character 1 bit is to be written over a destination area O bit, it changes the 
destination area to a 1 bit. 


o If a text-character 1 bit is to be written over a destination area 1 bit, the result of com- 
bining the source and destination is a O bit. In other words, whatever the current state 


of a destination area bit, a 1 bit in the source changes it to the opposite state. 


o Zero bits in the text character definition have no effect on the destination area. 
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Example aligns left edges of both areas. 


a 
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See ee Le 
ee ee ek 
Done orecpeg 


Text Character Memory Area Result of printing it in complement 


mode with left edges aligned as shown. 





Figure 4-2: Complement Mode 


If you set the INVERSVID flag to a 1, it will change all 1 bits to O bits and vice versa in a text 
or other RastPort writing operation before writing them into the destination area. If the 
drawing mode at that time is JAM2, then the pattern colors will be reversed as well. If 
DrawMode is INVERSVID, you can produce inverse video characters. 


Here is an example showing each of the three modes of text that you can produce. Again it 
assumes that your RastPort has been set up elsewhere. 


/* sample routine to print four lines of text to 
* the screen, each line in a different mode */ 


test( ) 

SetAPen( rp, 2); /* use color 2 as primary drawing color */ 
SetBPen( rp, 3); /* use color 3 as secondary drawing color */ 
Move( rp, 0, 6); /* move the drawing position near upper left */ 


SetDrMd( rp, JAM1 );_ /* Jam 1 color into target raster */ 

Text( rp, ” This is JAM1 mode’, 17 ); 

Move{( rp, 0, 46); /* move the drawing position for next line */ 

SetDrMd( rp, JAM2 );_ _/* Jam 2 colors into target raster */ 

Text( rp, ” This is JAM2 mode”, 17 ); 

Move( rp, 0, 86); /* move the drawing position for next line * / 
/* use exclusive-or (COMPLEMENT) to write */ 

SetDrMd( rp, COMPLEMENT ); 

Text( rp, ” This is COMPLEMENT mode’, 23 ); 

Move( rp, 0, 126 ); 

SetDrMd(rp,JAM1+INVERSEVID); 

Text( rp, “INVERSE”, 7 ); 


return; 


} 
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Effects of Specifying Font Style 


When you call OpenFont(), specifying certain style characteristics, the system searches the 
loaded fonts to find the closest match to the font you requested. If the remainder of the charac- 
teristics match what you have requested, but the style does not match, the text routines 
AskSoftStyle() and SetSoftStyle() create a font styled as you have requested by modifying 
the existing font (that is, modifying a normal font to italic or bold by modifying its characters.) 
Because many fonts do not lend themselves to such modifications, it is always preferred that the 
font of the specific style be loaded for use. The system always tries to find the exact specified 
font before attempting to modify another to fit your request. 


If there is a font present in the system that matches your OpenFont() request both in name 
and size, but not in style, (as determined by looking at the font style field), you may use 
SetSoftStyle() to generate the selected style algorithmically as follows: 


NORMAL 


The font is used exactly as defined. 


UNDERLINED 


An underline is generated one pixel below the baseline position. 


ITALIC 


The character is given a slant to the right, starting from the bottom line, and shifting 
subsequent upward line positions to the right one bit position for every second count up 
from the bottom of the character. 


EXTENDED 
This attribute cannot be set with SetSoftStyle(). See “Font Style” below. 


If you use a font that has the various style characteristics built in, rather than generated, the 
internal spacing and kerning tables tell the system how to leave the proper amount of space 
between characters if you are simply printing them one at a time. 


If you ask Text() to output the characters individually, Text() calculates character positioning 
and width based on the normal width and inter-character spacing that it finds in the font 
descriptor. After printing one or more characters, it automatically positions the drawing pen 
(cp_x) at the position it believes to be correct for the next output character. This may cause 
adjacent characters to overlap when printed individually. 


There is a solution to this problem. If you are using generated style for a font, you must take 
care to build your output strings of characters before calling Text() to output them. Text() 


can handle character strings, correctly generating the desired style with correct inter-character 
spacing. 
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To increase inter-character spacing, you can set a field called rp_TxSpacing in the RastPort. 
The spacing is specified in pixels. 


Adding a New Font to the System 


The ROM Exec code maintains a list of the text fonts that are currently linked into the system. 
To add another font, you must open a disk font using the diskfont library or define the font. 
You must also reserve some memory where the font can be loaded, move the font definition into 
that memory area, and link the font name and location into the system font list. 


Using a Disk Font 


To use an existing disk font, you must open the diskfont library and open a disk font. Here are 


the program fragments you need to open the library. This gives you access to whatever rou- 
tines the diskfont library contains: 


struct Library *DiskfontBase; 


DiskfontBase = (struct Library *) 
OpenLibrary(” diskfont.library” ,O); 


Before trying to use the diskfont routines, you should check that the OpenLibrary() call 
returned a value other than NULL. 


Here is the program fragment you need to actually load a disk-based font. It assumes that you 
already know the name of the font you want to load. 


struct TextFont *font; 
struct TextAttr myTextAttr; 


font = OpenDiskFont(&myTextAttr); 
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Finding Out Which Fonts Are Available 


The function AvailFonts() fills in a memory area designated by you to hold a list of all of the 
fonts available in the entire system. AvailFonts() searches the AmigaDOS directory path 
currently assigned to FONTS: and locates all available fonts. If you haven’t issued a DOS 


ASSIGN command to change the FONTS: directory path, the system will search the sys:fonts 
directory. 


The test program ‘“‘whichfont.c’’ at the end of this chapter provides a list of the fonts you can 
use and shows you how to find the appropriate items to put into the text attribute data struc- 
ture for the call to OpenDiskFont/(). 


Contents of a Font Directory 


In a font directory, you will usually find two names for each font type. A typical pair of entries 
in the fonts directory is as follows: 


sapphire.font 
sapphire(dir) 


The file named sapphire.font does not contain the actual font. It contains the description of the 
contents of that font family. The contents are described by a FontContentsHeader and one 
or more FontContents data structure entries. The FontContentsHeader structure is 
defined in libraries/diskfont.h as: 


struct FontContentsHeader { 
UWORD §fch_FileID; /* FCH_ID */ 
UWORD  fch_NumEntries; /* the number of FontContents elements */ 
/* FontContents (1 or more) follow here */ 
I 


where 


fch_FileID 
is simply a numeric identifier for this file type. The value is Oxf00. 


fch_NumEntries 
says how many entries of type FontContents follows this header. 
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The FontContents structure is defined as follows: 


struct FontContents { 
char fe_FileName[MAXFONTPATH]; 
UWORD fc_YSize; 
UBYTE fc_Style; 
UBYTE  fc_Flags; 


}3 
where 


fc_FileName 
is the pathname that AmigaDOS must follow to find the actual diskfont descriptive 
header, along with the TextFont data structure of which this font is composed. Once 


AmigaDOS reaches the path named in FONTS:, it finds the filename by the path shown 
in this entry in FontContents. 


fe_YSize, fc_Style, and fc_Flags 
correspond to their equivalents in the TextAttr data structure (ta_YSize, ta_Style, 
and ta_F lags). 


As an example, a typical entry in sapphire.font is: 


”sapphire/14”, a null-terminated string, padded out with 
zeros for a length of MAXFONTPATH bytes, 

14, the value for fc_YSize, 

00, the value for fc_Style, 

60 (hex) the value for fc_Flags. 


This entry indicates that the actual DiskFontHeader for the font to be loaded is in path 
FONTS:sapphire/14. This means that the sapphire subdirectory in the fonts directory must 
have a file named 14 in order to allow this font to be loaded. 


The Disk Font 


A disk font is constructed as a loadable, executable module. In this manner, AmigaDOS can be 
used to perform LoadSegment() and UnloadSegment() on it. AmigaDOS can therefore allo- 
cate memory for the font, and return the memory when the font is unloaded. The contents of 
the DiskFont are described in the include-file libraries/diskfont.h. The most significant item in 


this structure, the embedded TextFont structure, is described below in the topic ‘‘Defining a 
Font.” 


202 Text 


Defining a Font 


To define a font, you must specify its characteristics using the TextFont structure. The 
TextFont structure is specified in the include file named graphics/tezt.h. The following topics 
show the meaning of the items in a TextFont structure. Following the structure description is 
an example showing a four-character font, which is defined using this structure and can be 
linked into the system using AddFont(). 


THE TEXT NODE 


The first item in the TextFont structure is a listNode by which the system can link this font 
structure into the system TextFonts list. You specify the name of the font using the name 
pointer field of the font listNode. 


For example: 


struct TextFont suitFont; 
/* name chosen for sample font here */ 
suitFont.textNode.ln_name = “‘suits.font’’; 


FONT HEIGHT 


You specify the height in the ySize variable. All characters of the font must be defined using 
this number of lines of data even if they do not require that many lines to contain all font data. 
Variable-height fonts are not supported. 


For example: 


suitFont.ySize = 8; /* all characters are 8 lines high */ 


FONT STYLE 


You can specify the style of the font by specifying certain bits as 1s in the TextFont Style 
variable. The value of Style is determined by the sum of the style bits, defined as: 


Text 203 


NORMAL (value = 0), The text font is used exactly as defined. 
UNDERLINED (value = 1), The font is underlined. 

BOLD (value = 2), The font is bold. 

ITALIC (value = 4), The font is italic. 

EXTENDED (value = 8), The font is stretched out (width). 


In the font structure, these bits indicate style attributes as intrinsically a part of the font; that 
is, the font already has them and you can never take them away. 


FONT PREFERENCES 


This variable provides additional information that tells the font routines how to create or access 


the characters. The Preferences variable is composed of the sum of the preference bits, defined 
as follows: 


FPB_ROMFONT (value = 0) 


The font is located in ROM. If you are making up your own font, this variable will not 
be zero unless you are burning new system ROMs yourself. 


FPB_REVPATH (value = 2) 
The font is designed to be rendered from right to left (for example, Hebrew). 


FPB_PROPORTIONAL (value = 32) 


The characters in the font are not guaranteed to be xSize wide (see “Font Width” 
below). Each character has its own width and positioning in the character space. The 
bit-packing of the characters is of great importance, as described below. The variables 
modulo, charloc, and charspace define how the characters are defined and bit- 
packed. 


FONT WIDTH 


The xSize variable specifies the nominal width of the font. For example: 


suitFont.tf_XSize = 14; /* specify 14 bits width */ 
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FONT ACCESSORS 


If you have added a font to the system list, it is possible that more than one task will be access- 
ing a character font. A variable in the font structure keeps track of how many accessors this 
font currently has. Whenever you call OpenFont() or OpenDiskFont(), this variable is incre- 
mented for the font and decremented by CloseFont(). The font accessor value should never be 
reduced below zero. This accessor count should be initialized to zero before you first link a new 
font into the system, but it is managed by the system after the link is performed. 


If you wish to remove a font from the system to free the memory that it is currently using, you 
must ensure that the number of accessors is zero before ordering its removal. 


CHARACTERS REPRESENTED BY THIS FONT 


It is possible to create a font consisting of 0 to 255 characters. Some fonts can be exceedingly 
large because of their design and the size of the characters. For this reason, the text system 
allows the design and loading of fonts that may consist of only a few of the characters. The 
variables tf_loChar and tf_hiChar specify the numerical values for the characters represented 
in this font. As an example, one font could contain only the capital letters. A second font could 
contain the small letters, and a third could contain the punctuation marks and numerals. 
Depending on the size of the font itself, you may arrange to subdivide the font even further. 


In the example that is being built for this chapter, a font consisting of four playing card suits is 
being constructed. This font might consist of only four items, one for each of the playing suits. 
For example: 


suitFont.tf_LoChar = 160; 
/* value to use for first character chosen at whim */ 


suitFont.tf_HiChar = 163; 
/* 160 to 163 range says that there are 4 characters 
* represented in this font */ 


As part of the character data, in addition to defining the included character numbers, you must 
also define a character representation to be used as the image of a character number requested 


but not defined in this font. This character is placed at the end of the font definition. 


For this example, any character number outside the range of 160-163 inclusive would print this 
‘not in this font” character. 
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THE CHARACTER DATA 


The font structure includes a pointer to the character set data along with descriptions of the 


how the data is packed into an array. The variables used are defined in graphics/tezt.h; their 
usage is as follows: 


tf_CharData 


This is a pointer to the memory location at which the font data begins. This is the 
bit-packed array of character information. 


tf_Modulo 


This is the row modulo for the font. The font is organized with the top line of the first 
character bit adjacent to the top line of the second character and so on. 


For example, if the bit-packed character set needs 10 words of 16 bits each to hold the 
top line of all of the characters in the set, then the value of the modulo will be 20 
(bytes). Twenty is the number which must be added to the pointer into the character 
matrix to go from the first line to the second line of a specific character. 


tf_CharLoc 


This is a pointer to an array of paired values. The values are the bit offset into the 
bit-packed character array for this character, and the size of the character in bits. 
Expressed in C language, this array of values can be expressed as: 


struct charDef = { 
WORD charOffset; 
WORD charBit Width; 


} 


In the program definition, the array to which charLoc points can be expressed as: 


struct charDef suitDef[5]; 
/* define an array of four sets of character and one "not a 
* character” bit-packed placement and width information */ 


For all proportional fonts, there must be one set of descriptors for each character 
defined in the character set. 


tf_CharSpace 


This is a pointer to an array of words of proportional spacing information. This 1s the 
width of each character rectangle, in other words, how many bits width are used to con- 
tain the edge-to-edge width of this character’s bit definition. 


For example, a narrow character may still be stored within a wide space (see figure 4-3). 
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(Value = 5 for this example) Kern = 2 





Figure 4-3: CharSpace Figure 
If this pointer is null, use the nominal width for each character (xSize). 


tf_CharKern 
This is a pointer to an array of words of character kerning data. Kerning is the offset 
from the character pointer to the start of the bit data (see figure 4-4). If this pointer is 
null, kerning is zero. 


(Value = 2 for this example) 





Figure 4-4: CharKern Figure 


A COMPLETE SAMPLE FONT 


The sample font below pulls together all of the pieces from the above sections. It defines a font 
whose contents are the four suits from a set of playing cards: clubs, hearts, spades and 
diamonds. 


The suits are defined as proportionally spaced to provide a complete example, even though each 


suit could as easily have been defined in a 14-wide-by-8-high matrix. There is an open-centered 
square, which is used if you ask for a character not defined in this font. 
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* A complete sample font. To test this font, the following must be done: 


In the AmigaDOS SYS:fonts directory, install a file named 
test. font, containing 264 bytes. 


The first two bytes must contain the value hex Of00, the identifier 
for a font header. 


The next word (2 bytes), should contain the value 0001, which is 
the number of FontContents elements. There will be only one 
font in the directory that this font description covers. 


Follow this header material with the ASCII value for ’test/8’; 

the next 250 bytes should be set to zero. This represents the 
pathname for AmigaDOS to follow from the directory SYS:fonts to 
reach this test font. *test’ is the directory it should go to and 

8’ is the font file itself, as assembled and linked below. 


The next two bytes (as one word) contain the font YSize; in this 
case, 0008. 


The next byte contains the font Flags, in this case 00. 

The last byte contains the font characteristics, in this case hex 60. 
This says it is a disk-based font (bit 1 set) and the font has been 
removed (bit 7 set), saying that the font is not currently resident. 


Summary (all in hex) of test.font file: 


Of00 0001 test/8 ........ 0008 00 60 
word word 256-bytes...... word byte byte 


Create a directory named ’test’ in SYS:fonts. 


Copy the file created by assembling and linking the test font 
below into a file named ’8’ in subdirectory SYS:fonts/test. 


Use the font under the Notepad program or any other. It defines ASCII 
characters ’a’ ’b’ ’c’ and ’d’ only. All other characters print an 
>unknown character,” a rectangle. 


INCLUDE ” exec /ty pes.1” 
INCLUDE ” exec /nodes.i” 
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INCLUDE 


fontName: 


font: 


” libraries /diskfont.i” 


MOVEQ #0,D0 


RTS 
DC.L 
DC.L 
DC.B 
DC.B 
DC.L 
DC.W 
DC.W 
DC.L 


DS.B 


DC.L 
DC.L 
DC.B 
DC.B 
DC.L 
DC.L 
DC.W 
DC.W 
DC.B 
DC.B 
DC.W 
DC.W 


‘provide an easy exit in case somebody 
‘tries to RUN this file instead of loading it. 


0 - In_Succ 

0 - In _ Pred 
NT_FONT ; In_Type 

0 > In_Pri 
fontName - In_Name 
DFH_ID ; FileID 

1 ; Revision 

0 - Segment 
MAXFONTNAME _— ; Name 

0 > In_Succ 

0 - In_Pred 
NT_FONT ; In_Type 

0 > In_Pri 
fontName - In_Name 

0 ; mn_ReplyPort 
fontEnd-font ; mn_Length 
8 : tf_YSize 

0 ; tf_Style 
FPF_DESIGNED+FPF_PROPORTIONAL : tf_Flags 
14 : tf_XSize 

6 ; tf_Baseline 


* baseline must be no greater than YSize-1, otherwise algorithmically- 
* generated style (italic particularly) can corrupt system memory. 


DC.W 
DC.W 
DC.B 
DC.B 
DC.L 
DC.W 


DC.L 


DC.L 
DC.L 


1 

0 

97 

100 
fontData 
8 


fontLoc 


fontSpace 
fontKern 


- tf_BoldSmear 

; tf_Accessors 

- tf LoChar 

- tf_HiChar 

- tf_CharData 

- tf Modulo, no of bytes to add to 
- data pointer to go from one row of 
- a character to the next row of it. 
- tf CharLoc, bit position in the 

- font data at which the character 
- begins. 

. tf_CharSpace 

- tf_CharKern 
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FOO GOO OO GCI aa GK kak aK 

* These are the suits characters that this font data defines. ASCII lower-case 

* ab,c,d. The font descriptor says that there are 4 characters described here. 
* The fifth character in the table is the character to be output when there is 


* no character in this character set that matches the ASCII value requested. 
* 


* 


* 97 98 99 100 256 

F< > on >< >< > 
* @aad @@e@ @ @ @@Q@ GAGOQGGEGAQGE@ 
* @@QGQ@ aacae @@e@Ga@ @@a G@GGO@ @@ @@ 
*  @aGQeGGGQ QGAGAGQGQ @@@G@@ CG @ @G@ @@ @@ 
* @@QGQGOQ GAGAGEGGQEGOQ @AGCGEGGOQ GQCAGQGGQ@E@ @@ @@ 
* Q@GaQ@ @G@ @ ace @O CCE Ge a @ @@ @@ 
* @G@ @ @@@ @ @@ @@ 
* @ @Ga@a@@ @ @@G@@@ QEAAGAGAGEAGQ 


KRKEKKKKKEKKEKKKHEKREKEKKEEKKKKKEKRKEKKEEKEKEKRKEKEKEKEKKEKRKEKEKEKEEKKEKRKEKRKEKR KKK KEK KKK KKK KK 


fontData: 
DC.W $07 1C0,$08040,$070F F ,$0F 000 
DC.W SOF BE3,$0E0E0, $0F 8CO,$03000 
DC.W $07F CF ,$0F 9F3,$026C0,$03000 
DC.W $03F9F $OF FFF ,$0FFC0,$03000 
DC.W $01F0E,$0B9F3,$026C0,$03000 
DC.W $00E00,$080E0,$020C0,$03000 
DC.W $00403,$0E040,$0F 8FF ,$0F000 
DC.W $00000,$00000,$00000,$00000 
DC.W $00000,$00000,$00000 ,$00000 


* font data is bit-packed edge to edge to save space; that’s what the 
* fontLoc 1s all about. 


fontLoc: 


DC.L $00000000B, ,$0000B000B,$0001 60007 ,$0001 DOOOB 
DC.L $00028000C 


* Kach pair of words specifies how the characters are bit-packed. For 
* example, the first character starts at bit position 0000, and is 000B 

+ (11) bits wide. The second character starts at bit position O00B and 
* is OOOB bits wide, and soon. Tells font handler how to unpack the 
* bits from the array. 


fontSpace: 
DC.W  000012,000012,000008,000012,000013 
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* fontSpace array: Use a space this wide to contain this character 
* when it 1s printed. 


fontKern: 

DC.W 000001 ,000001 ,000001 ,000001 ,000001 
fontEnd: 

END 


Sample Program 


The following sample program asks AvailFonts() to make a list of the fonts that are available, 
then opens a separate window and prints a description of the various attributes that can be ap- 
plied to the fonts, in the font itself. Notice that not all fonts accept all attributes (garnet9 for 
example, will not underline). If you run this program, note also that not all fonts are as easily 
readable in the various bold and italicized modes. This rendering is done in a fixed manner by 
software and the fonts were not necessarily designed to accept it. It is always best to have a 


font that has been designed with a bold or italic characteristic built in rather than trying to 
italicize and embolden an existing plain font. 


/* >whichfont.c” */ 
#-define AFTABLESIZE 2000 


#include ” exec/types.h” 
#include ” exec/io.h” 


#include ”exec/memory.h” 


#include ” graphics/gfx.h” 
#include ”hardware/dmabits.h” 
#include ”hardware/custom.h” 
#include ”hardware/blit.h” 
#include ” graphics/gfxmacros.h” 
#include ” graphics /copper.h” 
#include ” graphics/view.h” 
#include ” graphics/gels.h” 
#include ” graphics/regions.h” 
#include ” graphics/clip.h” 
#include ” exec/exec.h” 
#include ” graphics/text.h” 
#include ” graphics/gfxbase.h” 
#include ”devices/keymap.h” 
#include ” libraries/dos.h” 
#include ” graphics/text.h” 
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#include ” libraries/diskfont.h” 


#include ” intuition /intuition.h” 


struct AvailFonts *af; 
struct AvailFontsHeader *afh; 
extern int AvailFonts(); 


struct TextFont *tf; 
struct TextAttr ta; 


ULONG DosBase; 
ULONG DiskfontBase; 
ULONG IntuitionBase; 
ULONG GfxBase; 


struct NewWindow nw = { 


10, 10, /* starting position (left,top) */ 
620,40, /* width, height */ 

=1571; /* detailpen, blockpen */ 

0, /* flags for IDCMP */ 


WINDOWDEPTH]|WINDOWSIZING|WINDOWDRAG|SIMPLE_REFRESH| 
ACTIVATE|GIMMEZEROZERO, /* window gadget flags */ 


0, /* pointer to Ist user gadget */ 
NULL, /* pointer to user check */ 
*Text Font Test”,  /* title */ 

NULL, /* pointer to window screen */ 
NULL, /* pointer to super bitmap */ 
100,45, /* min width, height */ 
640,200, /* max width, height */ 
WBENCHSCREEN}; 


struct Window *w; 
struct RastPort *rp; 


SHORT text_styles| |] = { FS_NORMAL, FSF_UNDERLINED, FSF_ITALIC, FSF_BOLD, 
FSF_ITALIC | FSF_BOLD, FSF_BOLD | FSF_UNDERLINED, 
FSF_ITALIC | FSF_BOLD | FSF_UNDERLINED }; 


char *text| |] = { ” Normal Text”, ” Underlined”, ” Italicized”, ” Bold”, 
” Bold Italics”, ” Bold Underlined”, 
” Bold Italic Underlined” }; 

char textlength[{ |] = { 12, 11, 11, 5, 13, 16, 23 }; 


char *pointsize|| ass { ” 0” ,” 1?” 2 8 4” ” a” 6”,.” Co 8” ” 9” , 
EOP PIE 1 1s 1a 16 dae 1S 
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> 90” a 91” me 99” = 93” — 94” - 95” — 96” hs QF? - IR” as 99” 
” 30” _ 31” }; 


char fontname[40]; 


char dummy/100]; /* provided for string length calculation */ 
char outst|100); /* build something to give to Text, see note in the 
* program body about algorithmically generated styles */ 
main() 
{ 


UBYTE fonttypes; 

int j,k,m; 

SHORT afsize; 

SHORT style; 

SHORT sEnd; /* numerical position of end of string terminator, 
* and coincidentally the length of the string. */ 


if( (DosBase = OpenLibrary(” dos.library”, 0)) =— NULL) exit(-1); 

if((DiskfontBase—OpenLibrary(” diskfont. library” ,0))==—NULL) exit(-4); 
if((IntuitionBase—OpenLibrary(” intuition.library” ,0))—=—NULL) exit(-2); 
if((GfxBase—=OpenLibrary(” graphics. library” ,0))—=—=NULL) exit(-3); 


tf—NULL,; /* no font currently selected */ 
afsize = AFTABLESIZE; /* show how large a buffer is available */ 
fonttypes = Oxff; /* show us all font types */ 


afh = (struct AvailFontsHeader +) AllocMem(afsize, MEMF_CLEAR); 
if(afh == NULL) exit(-5); 


printf(” \nSearching for Fonts\n”); 
AvailFonts(afh, afsize, fonttypes); 


af = (struct AvailFonts *) &afh/{1]; /* bypass header to get to the 
* first of the availfonts */ 


for (j = 0; j < afh->afh_NumEntries; j++) 


if((af->af_Attr.ta_Flags & FPF_REMOVED) || 
(af->af_Attr.ta_Flags & FPF_REVPATH) || 
((af- > af_Type&AFF_MEMORY)&& 
(af->af_Attr.ta_Flags&FPF_DISKFONT))) 
/* do nothing if font is removed, or if font 
* designed to be rendered rt->left (simple 
* example writes left to right) or if font 
* both on disk and in ram, don’t list it twice. */ 
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/* AvailFonts performs an AddFont to the system list; if run twice, you 
* get two entries, one of ”af_Type 1” saying that the font is memory- 

* resident, and the other of ”af_Type 2” saying the font is disk-based. 
* The third part of the if-statement lets you tell them apart if you 

* are scanning the list for unique elements; it says "if it’s in 

* memory and it is from disk, then don’t list it because you’ll find 

* another entry in the table that says it is not in memory, but is on 

* disk.” (Another task might have been using the font as well, creating 
* the same effect.) 


+) 


else 


{ 


printf(”\nFont name found was: %|s” ,af- >af_Attr.ta_Name); 
printf(” and its point size is: %ld” ,af->af_Attr.ta_YSize); 

/* Style parameter is in af->af_Attr.ta_Style, 

* Flags parameter is in af- >af_Attr.ta_Flags. 


7 
} 
af++: 


} 


/* now that we’ve listed the fonts, let’s look at them */ 


w= (struct Window +)Open Window(&nw); 
rp —= w- >RPort; 


for(m=0; m<2; m++) /* do normal video, then inverse video */ 


{ 


af = (struct AvailFonts *)&afh(1|; /* reset value of af to original */ 
SetAPen(rp,1); 


if(m == 0)SetDrMd(rp,JAM1); 
else SetDrMd(rp, JAM1+INVERSVID); 


/* now print a line that says what font and what style it is */ 


for (j=0; j < afh->afh_NumEntries; j++) 


{ 


CStringAppend(&fontname|0],af- >af_Attr.ta_Name); 
/* copy name into build-name area */ 
/* already has ”.font” onto end of it */ 


ta.ta_Name = &fontname|0}; 
ta.ta_YSize = af->af_Attr.ta_YSize; /* ask for this size */ 
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ta.ta_Style — af->af_Attr.ta_Style; /* ask for designed style */ 
ta.ta_Flags = FPF_ROMFONT|FPF_DISKFONT| 
FPF_PROPORTIONAL|FPF_DESIGNED, 
/* accept it from anywhere it exists */ 
style = ta.ta_Style; 


if('((af->af_Attr.ta_Flags & FPF_REMOVED) || 
(af->af_Attr.ta_Flags & FPF_REVPATH) || 
((af- > af_Type&AFF_MEMORY)&& 
(af->af_Attr.ta_Flags&FPF_DISKFONT)))) 


/* this is an IF-NOT, the reverse of the earlier if-test on 
* these same parameters 


+) 

{ 
tf = (struct TextFont *) OpenDiskFont(&ta); 
if (tf !== 0) 
{ 


SetFont(w->RPort, tf); 

for(k=0; k<7; k++) 
{ 
style = text_styles|k]; 
SetSoftStyle(w- >RPort,style,255); 
SetRast(rp,0); /* erase any previous text */ 
Move(rp,10,20); = /* move down a bit from the top */ 
sEnd = CStringAppend(&outst(0],af- > af_Attr.ta_Name); 
sEnd = sEnd + CStringAppend(outst|sEnd],” ”); 
sEnd = sEnd + CStringAppend(outst|sEnd], 

pointsizelaf- >af_Attr.ta_YSize]): 

sEnd = sEnd + CStringAppend(&outst|sEnd],” Points, ” ); 
CStringA ppend(outst|sEnd],text/|k]); 
Text(rp,doutst|0],CStringAppend(&dummy/(0],£outst|0})); 


/* Have to build the string before sending it out to text IF 

* ALGORITHMICALLY GENERATING THE STYLE since the kerning and 
* spacing tables are based on the vanilla text, and not the 

* algorithmically generated style. If you send characters out 

* individually, it is possible that the enclosing rectangle of 

* a later character will chop off the trailing edge of a 

* preceding character. 


+7 
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| asi TuitelaiteTaitooilaateTuilotadiaaiinsadiasidiedieiadiaiaiietaiteiadietaiiodadiociaiediataiieiadieladieiaiteiediedaiieiadediaiadiedestadadietailedealadtadesiedadleduiiededaselaiesaiaaustated 
* This alternate method, when in INVERSVID, exhibits the problem described above. 
* 
* Text(rp,af- >af_Attr.ta_Name,STRLEN(af- > af_Attr.ta_Name)); 
* Text(rp,” ”,2); 
* Text(rp,pointsizelaf- >af_Attr.ta_YSize],2); 
* Text(rp,” Points, ”,9); 

x 


* Text(rp,text(k],textlength |k]); 
2k Ke 2 ok 2 ik fe 2 2 2 ok 2k 2c ok ok otc ok ok 2 2k 2k 2 2 2 2k ok 2K KK 2k a 2 ok 2 2k oe ok 2 ok 2k 2K 2 ok 2 2 2k 2 i 2k 2k ok 2 2 2 2 2c 2k 2k 2K 2K 2k ok 2K 2k ok ok 2k ok ok 2k ok 2K 2k ok 


Delay(40); = /* use the DOS time delay function 
* specifies 60ths of a second */ 


CloseFont(tf); /* close the old one */ 


/* NOTE: Even though you close a font, it doesn’t get unloaded from 
* memory unless a font with a different name is specified for loading. 
+ In this case, any font that has been closed (except the topaz set) 

* can have its memory area freed, and that font will no longer be 

* accessible. If you close a font to go to a different point size, it 

* will NOT cause a disk access. 


* 


\ /* end of if-tf-ne-O */ 
}  /* end of if-(in memory but from disk) */ 
af++; 
} /* Do next font now */ | 
} /* end of for-loop, controlled by m */ 


FreeMem(afh,AFTABLESIZE); 
CloseWindow(w); 
CloseLibrary(IntuitionBase); 
CloseLibrary(DosBase); 
CloseLibrary(DiskfontBase); 
CloseLibrary(GfxBase); 


j 


/* copy a string and return the number of characters added to a string. 
* Effectively returns the length of the string if not adding anything */ 
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int CStringAppend(dest, source) 
char *dest; 
char *source; 
{ 
int 1=0; 
char *s = source; 
char *d = dest; 
while (( 1 <79 )&&( *d = *s )) { d++; s+; i++; } 
/* if a NULL found in source, end the copy, but the NULL itself gets 
* copied over to the destination. If no NULL, then 79 characters get 
* copied, then a terminating NULL is added */ 
if(i < 79) return(i); 
else {*d = 0; return(i); } 
/* value returned is the position of the terminating NULL to 
* allow other strings to be appended simply using the next 
* append command in sequence */ 


Text 
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PART II 


Chapter 5 


Audio Device 


Introduction 


The Amiga has four hardware audio channels—two of the channels produce audio output from 
the left audio connector and two from the right. These channels can be used in many ways. 
You can combine a right and a left channel for stereo sound, use a single channel, or play a 
different sound through each of the four channels. 
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The audio software is implemented as a standard Amiga input/output device with commands 
that allocate audio channels and control the sound output. 


Some of the audio device commands isolate the programmer from idiosyncrasies of the special- 
chip hardware. You can also produce sound on the Amiga by directly accessing the hardware 
registers. For certain types of sound synthesis, this is more CPU-efficient. Some of the audio 
commands make most sound synthesis easier. Other commands enable your program to co- 
reside with other programs using the multitasking environment to produce sound at the same 
time. Programs can co-reside because the audio device handles allocation of audio channels and 
arbitrates among programs competing for the same resources. 


Most personal computers that produce sound have hardware designed for one specific synthesis 
technique. The Amiga uses a very general method of digital sound synthesis that is quite simi- 
lar to the method used in digital hi-fi components and state-of-the-art keyboard and drum syn- 
thesizers, with one significant difference. The Amiga has a tightly-coupled 68000 microprocessor 
capable of generating and modifying the digital data while the sound is playing. How much of 
the CPU you can afford to use for sound synthesis depends on your application. 


For programs that can afford the memory, playing sampled sounds gives you a simple and very 
CPU-efficient method of sound synthesis. When a sound is sampled, the amplitude of the 
waveform that represents a sound is measured (sampled) by an analog-to-digital converter at a 
fixed interval (period) in time. This results in a table of numbers. When the sound is played 
back by the Amiga, the table is fed by a DMA channel into one of the four digital-to-analog 
converters in the custom chips. The digital-to-analog converter converts the samples into vol- 
tages that can be played through amplifiers and loudspeakers, reproducing the sound. 


On the Amiga you can create sound data in many other ways. For instance, you can use tri- 
gonometric functions in your programs to create the more traditional sounds—sine waves, 
square waves, or triangle waves—by using tables that describe their shapes. Then you can 
combine these waves for richer sound effects by adding the tables together. Once the data is 
entered, you can modify it with techniques described in the section called ‘“‘Audio Functions and 
Commands.” 


For information about the limitations of the audio hardware and suggestions for improving sys- 
tem efficiency and sound quality, refer to the Amiga Hardware Reference Manual. 


The following works are recommended for information about computer sound generation in 
general: 


o Musical Applications of Microprocessors, by Hal Chamberlain (Hayden, 1980) 


o Foundations of Computer Music, by Curtis Roads and John Strawn (Cambridge: MIT 
Press, 1985) 
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o Digital Audio Signal Processing, by John Strawn (Los Altos, California: William Kauf- 
mann, Inc., 1985) 


Definitions 


Terms used in the following discussions may be unfamiliar. Some of the more important terms 
are defined below. 


Amplitude 


The height of a waveform, which corresponds to the amount of voltage or current in 
the electronic circuit. 


Amplitude modulation 


A means of producing special audio effects by using one channel to alter the amplitude 
of another. 


Buffer 


An area of continuous memory, typically used for storing blocks of data. 


Channel 
One “‘unit’’ of the audio device. 


Cycle 


One repetition of a waveform. 


Frequency 
The number of times per second a waveform repeats. 


Frequency modulation 


A means of producing special audio effects by using one channel to affect the period of 
the waveform produced by another channel. 


Period 


The time elapsed between the output of successive sound samples, in units of system 
clock ticks. 


Precedence 
Priority of the user of a sound channel. 


Sample 
Byte of audio data, one of the fixed-interval points on the waveform. 
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Volume 
The decibel level of sound coming from an audio channel. 


Waveform 


Graph that shows a model of how the amplitude of a sound varies over time— usually 
over one cycle. 


Audio Functions and Commands 


The first part of this section gives some general information about audio functions and com- 
mands. Following the general information there is a brief description of each command. For 
complete specifications, see the command and function reference section and the header files 
devices/audio.i and devices/audio.h in the “Include Files” appendix. 


AUDIO AS A DEVICE 


The audio device has much in common with the other I/O devices, so general information about 
device I/O is not repeated here. Before reading further, you should become familiar with the 
general description of device I/O in the Amiga ROM Kernel Reference Manual: Exec. 


Audio device commands use an extended [ORequest block instead of the standard [ORequest 
block. When using an audio command, refer to the devices/audio.1 and devices/audto.h files for 
the extended fields. 


SCOPE OF COMMANDS 


All audio commands (except for CMD_WRITE, ADCMD_WAITCYCLE, and CMD_READ) can 
operate on multiple channels. CMD_WRITE, ADCMD_WAITCYCLE, and CMD_READ 
operate on only one channel. You tell the audio device driver which channels you want a com- 
mand to act upon by setting the least significant four bits of the io_unit field of the 
TORequest block. You specify a 1 in the position of the channel you want to affect and a 0 in 
all other positions. For instance, you specify 5 (0101) to use channels 0 and 2. 


Certain of the audio device commands are actually higher-level functions in that they execute 
more than one audio device command with a single call. For example, the OpenDevice() func- 
tion, when used for the audio device, can perform an ADCMD_ALLOCATE command so that 
you can start writing data immediately. The CloseDevice() function can perform a 
ADCMD_FREE command to relinquish the channel(s) so you can exit immediately after closing 
the audio device. 
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ALLOCATION AND ARBITRATION 


You request the use of one or more audio channels by performing the ADCMD_ALLOCATE 
command. If possible,s ADCMD_ALLOCATE obtains the channels for you. When you request 
a channel, you specify a precedence number from -128 (the lowest precedence) to 127 (the 
highest). If a channel you want is being used and you have specified a higher precedence than 
the current user, ADCMD_ALLOCATE will “steal” the channel from the other user. Later on, 
if your precedence is lower than that of another user who is performing an allocation, the chan- 
nel may be stolen from you. If, after allocating a channel with the appropriate precedence, you 
raise the precedence to the maximum precedence with the ADCMD_SETPREC command, then 
no other allocation call can steal a channel from you. When you have finished with a channel, 
you must relinquish it with the ADCMD_FREE command to make it available for other users. 


Table 5-1 shows suggested precedence values. 


Predecence 


127 


90 - 100 


80 - 90 
79 
90 - 70 


-00 - 50 


-70 - O 


-100 - -80 
-128 


Table 5-1: Suggested Precedences for Channel Allocation 


Type of Sound 


Unstoppable. Sounds first allocated at lower precedence, then set 
to this highest level. 


Emergencies. Alert, urgent situation that requires immediate 
action. 


Annunciators. Attention, bell (CTRL-G). 
Speech. Synthesized or recorded speech (narrator.device). 


Sonic cues. Sounds that provide information that is not provided 
by graphics. Only the beginning of each sound (enough to recog- 
nize it) should be at this level; the rest should be set to sound 
effects level. 


Music program. Musical notes in music-oriented program. The 
higher levels should be used for the attack portions of each note. 
Notes should separately allocate channels at the start and free 
them at the end. 


Sound effects. Sounds used in conjunction with graphics. More 
important sounds should use higher levels. 


Background. Theme music and restartable background sounds. 


Silence. Lowest level (freeing the channel completely is preferred). 
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When you first perform a channel allocation request, the audio device provides you with an 
“allocation key’’ that is unique to the granting of your current allocation request. The alloca- 
tion key is also copied in the ioa_AllocKey field of your I/O control block and is used by all 
audio commands. Later, as you queue output requests to the audio device, the device can com- 
pare the allocation key in your request block to the key currently assigned for that channel (or 
channels). If the channel is stolen from you by another channel user that has a higher pre- 
cedence, the copy of the key maintained by the audio channel is changed. If you attempt to 
perform a command on a channel that has been stolen from you, an AUDIO_NOALLOCATION 
error is returned and the bit in the io_unit field corresponding to the stolen channel is cleared 
so you know which channel was stolen. 


There is no specific separate ‘‘audio resource.” Instead, the audio device, with its allocation key 
management, arbitrates the use of the physical audio resources. 


PERFORMING AUDIO COMMANDS 


To perform an audio command, sometimes you must use the system function BeginIO() rather 
than SendIO() or DoIO(). This is because the latter two functions clear the device-specific 
bits in the io_Flags field of the I[ORequest (bits 4 thru 7). Some of the audio commands use 
these bits to select options. If you use SendIO() or DoIO(), the flags will be set to 0 (FALSE), 


which may not be desirable. 


COMMAND TYPES 


Commands and functions for audio use can be divided into three categories: system functions, 
allocation /arbitration commands, and hardware control commands. There are also three audio 
device flags. 


The system functions are 
o OpenDevice() 
o CloseDevice() 
o BeginIO() 
o <AbortIO() 


The allocation/arbitration commands are 
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o0 ADCMD_ALLOCATE 
o ADCMD_FREE 
o ADCMD_SETPREC 
o ADCMD_LOCK 
The hardware control commands are 
o CMD_WRITE 
o0 ADCMD_FINISH 
o ADCMD_PERVOL 
o CMD_FLUSH 
o CMD_RESET 
o ADCMD_WAITCYCLE 
o CMD_STOP 
o CMD_START 
o CMD_READ 


The following paragraphs describe each function and command. 


SYSTEM FUNCTIONS 


These are standard Amiga device functions. They are used for communication with the device. 


OpenDevice() 


The audio device adds to the normal operation of this function. When you open the audio dev- 
ice with a nonzero ioa_Length field, OpenDevice() will attempt to allocate channels based on 
allocation mask just as if you had called the ADCMD_ALLOCATE command. This allocation 
is done with the ADIOF_NOWAIT flag set, so ADCMD_ALLOCATE will return immediately if 
it fails. If you are opening the device and are not ready to have a channel allocated to you just 
then, set the ioa_Length field to zero. 
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CloseDevice() 


When used with the audio device, CloseDevice() performs an ADCMD_FREE command on 
any channels selected by the io_Unit field. If you have different allocation keys for the chan- 
nels you are using, you cannot use this function to close all of them at once. Instead, you will 
have to issue one ADCMD_FREE command for each unique allocation that you are using. 
After issuing the ADCMD_FREE command(s), you can call CloseDevice(). 


BeginIO() 


Audio use of this function differs from normal use only in that it takes a pointer to an 
IOAudio structure as its only argument. 


AbortIO() 


This function can be used to cancel requests for ADCMD_ALLOCATE, ADCMD_LOCK, 
CMD_WRITE, or ADCMD_WAITCYCLE. When used with the audio device, AbortIO() 


always succeeds. 


ALLOCATION/ARBITRATION COMMANDS 


These commands allow the audio channels to be shared among different tasks and programs. 
None of these commands can be called from interrupt code. 


ADCMD_ALLOCATE 


This command gives access to channels. You perform this command with a pointer to a data 
array that describes the channels you want to allocate. For example, if you want a pair of 
stereo channels and you have no preference about which of the left and right channels the sys- 
tem will choose for the allocation, you can pass the command a pointer to an array containing 
3, 5, 10, and 12. Channels 0 and 3 output sound on the left side, and channels 1 and 2 on the 
right side. Table 5-2 shows how this array corresponds to all the possible combinations of a 
right and a left channel. 
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Table 5-2: Possible Channel Combinations 


Decimal 
Channel 3 Channel 2 Channell Channel 0 Value of 
left right right left Allocation Mask 
0 0 1 1 3 
0 1 0 1 5 
1 0 1 0 10 
1 1 0 0 12 


How ADCMD_ALLOCATE Operates. The ADCMD_ALLOCATE command tries the first 
combination, 3, to see if channels O and 1 are not being used. If they are available, the 3 is 
copied into the io_unit field and you get an allocation key for these channels. You copy the 
key into other I/O blocks for the other commands you may want to perform using these chan- 
nels. When finished with the channels, you perform the ADCMD_FREE command. If channels 
O and 1 are being used, ADCMD_ALLOCATE tries the other combinations in turn. If all the 
combinations are in use, ADCMD_ALLOCATE checks the precedence number of the users of 
the channels and finds the combination that requires it to steal the channel or channels of the 
lowest precedence. If all the combinations require stealing a channel or channels of equal or 
higher precedence, the I/O request ADCMD_ALLOCATE fails. Precedence is in the In_Pri 


field of the io_Message in the IORequest block you pass to ADCMD_ALLOCATE;; it has a 
value from -128 to 127. 


The ADIOF_NOWAIT Flag. If you need to produce a sound right now and otherwise you 
don’t want to allocate, set the ADIOF_NOWAIT flag to 1. This will cause the command to 
return an IJOERR_ALLOCFAILED error if it cannot allocate any of the channels. If you are 
producing a non-urgent sound and you can wait, set the ADIOF_NOWAIT flag to 0. Then, the 
TORequest block returns only when you gets the allocation. If ADIOF_NOWAIT is set to 0, 
the audio device will continue to retry the allocation request whenever channels are freed until 
it is successful. If the program decides to cancel the request, AbortIO() can be used. 


ADCMD_ALLOCATE Examples. The following are some more examples of how to tell 
ADCMD_ALLOCATE your channel preferences. If you want any channel, but want to try to 
get a left channel first, use an array containing 1, 8, 2, and 4: 


0001 
1000 
0010 
0100 
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If you want only a left channel, use 1 and 8 (channels O and 3): 


0001 
1000 


For a right channel, use 2 and 4 (channels 1 and 2): 


0010 
0100 


To produce special effects, such as hardware-controlled amplitude and frequency modulation, 
you may need to allocate channels that can be ‘‘attached”’ to each other. The following alloca- 
tion map specifies the allowable combinations. (For further information about amplitude and 
frequency modulation, see the Amiga Hardware Reference Manual.) 


0011 3 
0110 6 
1100 12 


If you want all the channels, use the following allocation map: 


1111 15 


If you want to allocate a channel and keep it for a sound that can be interrupted and restarted, 
allocate it at a certain precedence. If it gets stolen, allocate it again with the ADIOF_NOWAIT 
flag set to 0. When the channel is relinquished, you will get it again. 


The Allocation Key. If you want to perform multi-channel commands, all the channels must 
have the same key since the I[ORequest block has only one allocation key field. The channels 
must all have that same key even when they were not allocated simultaneously. If you want to 
use a key you already have, you can pass in that key in the allocation key field and 
ADCMD_ALLOCATE can _ allocate other channels with that existing key. The 
ADCMD_ALLOCATE command returns a new and unique key only if you pass in a zero in the 
allocation key field. 


ADCMD_FREE 


ADCMD_FREE is the opposite of ADCMD_ALLOCATE. When you perform ADCMD_FREE 
on a channel, it does a CMD_RESET command on the hardware and ‘“‘unlocks’’ the channel. It 
also checks to see if there are other pending allocation requests. You do not need to perform 


ADCMD_FREE on channels stolen from you. 
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ADCMD_SETPREC 


This command changes the precedence of an allocated channel. As an example of the use of 
ADCMD_SETPREC, assume that you are making sound of a chime that takes a long time to 
decay. It is important that user hears the chime but not so important that he hears it decay all 
the way. You could lower precedence after the initial attack portion of the sound to let another 
program steal the channel. You can also set the precedence to maximum (127) if you cannot 
have the channel(s) stolen from you. 


ADCMD_LOCK 


The ADCMD_LOCK command performs the ‘‘steal verify”? function. When a user is attempt- 
ing to steal a channel or channels, ADCMD_LOCK gives you a chance to clean up before the 
channel is’ stolen. You’ perform a ADCMD_LOCK command right after the 
ADCMD_ALLOCATE command. ADCMD_LOCK does not return until a higher-priority user 
attempts to steal the channel(s) or you perform an ADCMD_FREE command. If someone is 
attempting to steal, you must finish up and ADCMD_FREE the channel as quickly as possible. 


ADCMD_LOCK is necessary only if you want to store directly to the hardware registers instead 
of using the device commands. If your channel is stolen, you are not notified unless the 
ADCMD_LOCK command is present, and this could cause problems for the user who has stolen 
the channel and is now using it. ADCMD_LOCK sets a switch that is not cleared until you per- 
form an ADCMD_FREE command on the channel. Canceling an ADCMD_LOCK request with 
AbortIO() will not free the channel. 


The following outline describes how ADCMD_LOCK works when a channel is stolen and when 
it is not stolen. 


1. User A allocates a channel. 
2. User A locks the channel. 
If User B allocates the channel with a higher precedence: 


3. User B’s ADCMD_ALLOCATE command is suspended (regardless of the setting of the 
ADIOF_NOWAIT flag). 


4. User A’s ADCMD_LOCK command is_ replied to with an _— error 
(ADIOERR_CHANNELSTOLEN). 


5. User A does whatever is needed to finish up when a channel is stolen. 
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6. User A frees the channel with ADCMD_FREE. 
7. User B’s ADCMD_ALLOCATE command is replied to. Now user B has the channel. 
If the channel is not allocated by another user: 
3. User A finishes the sound. 
4. User A performs the ADCMD_FREE command. 
5. User A’s ADCMD_LOCK command is replied. 
Never make the freeing of a channel (if the channel is stolen) dependent on allocating another 


channel. This may cause a deadlock. To keep a channel and never let it be stolen, set pre- 
cedence to maximum (127). Do not use a lock for this purpose. 


HARDWARE CONTROL COMMANDS 


The following commands change hardware registers and affect the actual sound output. 


CMD_WRITE 


This 1s a single-channel command and is the main command for making sounds. You pass the 
following to CMD_WRITE: 


o A pointer to the waveform to be played (must start on a word boundary and must be 
in memory accessible by the custom chips, MEMF_CHIP) 


o The length of the waveform in bytes (must be an even number) 
o Account of how many times you want to play the waveform 


If the count is 0, CMD_WRITE will play the waveform from beginning to end, then repeat the 
waveform continuously until something aborts it. 


If you want period and volume to be set at the start of the sound, you set the WRITE 
command’s ADIOF_PERVOL flag. If you do not do this, the previous volume and period for 
that channel will be used. This is one of the flags that would be cleared by DoIO() and 
SendIO(). The ioa_WriteMsg field in the I[ORequest block is an extra message field that 
can be replied at the start of the CMD_WRITE. This second message is used only to tell you 
when the CMD_WRITE command _ starts processing, and it is used only when the 
ADIOF_WRITEMESSAGE flag is set to 1. 
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If a CMD_STOP has been performed, the CMD_WRITE requests are queued up. 


The CMD_WRITE command does not make its own copy of the waveform, so any modification 
of the waveform before the CMD_WRITE command is finished may affect the sound. This is 
sometimes desirable for special effects. 


To splice together two waveforms without clicks or pops, you must send a separate, second 
CMD_WRITE command while the first is still in progress. This technique is used in double- 
buffering, which is described below. 


Double-buffering. By using two waveform buffers and two CMD_WRITE requests you can 
compute a waveform continuously. This is called double-buffering. The following describes how 
you use double-buffering. 

1. Compute a waveform in memory buffer A. 

2. Issue CMD_WRITE command A with io_Data pointing to buffer A. 

3. Continue the waveform in memory buffer B. 

4. Issue CMD_WRITE command B with io_Data pointing to Buffer B. 

5. Wait for CMD_WRITE command A to finish. 

6. Continue the waveform in memory buffer A. 

7. Issue CMD_WRITE command A with io_Data pointing to Buffer A. 

8. Wait for CMD_WRITE command B to finish. 

9. Loop back to step 3 until the waveform is finished. 

10. At the end, remember to wait until both CMD_WRITE command A and CMD_WRITE 


command B are finished. 


ADCMD_FINISH 


The ADCMD_FINISH command aborts (calls AbortIO()) the current write request on a chan- 
nel or channels. This is useful if you have something playing, such as a long buffer or some 
repetitions of a buffer, and you want to stop it. 


ADCMD_FINISH has a flag you can set (ADIOF_SYNCCYCLE) that allows the waveform to 


finish the current cycle before aborting it. This is useful for splicing together sounds at zero 
crossings or some other place in the waveform where the amplitude at the end of one waveform 
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matches the amplitude at the beginning of the next. Zero crossings are positions within the 
waveform at which the amplitude is zero. Splicing at zero crossings gives you fewer clicks and 
pops when the audio channel is turned off or the volume is changed. 


ADCMD_PERVOL 


ADCMD_PERVOL lets you change the volume and period of a CMD_WRITE that is in pro- 
gress. The change can take place immediately or you can set the ADIOF_SYNCCYCLE flag to 
have the change occur at the end of the cycle. This is useful to produce vibratos, glissandos, 
tremolos, and volume envelopes in music or to change the volume of a sound. 


CMD_FLUSH 


CMD_FLUSH aborts (calls AbortIO()) all CMD_WRITEs and all ADCMD_WAITCYCLEs 


that are queued up for the channel or channels. It does not abort ADCMD_LOCKs (only 
ADCMD_FREE clears locks). 


CMD_RESET 


CMD_RESET restores all the audio hardware registers. It clears the attach bits, restores the 
audio interrupt vectors if the programmer has changed them, and performs the CMD_FLUSH 
command to cancel all requests to the channels. CMD_RESET also unstops channels that have 
had a CMD_STOP performed on them. CMD_RESET does not unlock channels that have been 
locked by ADCMD_LOCK. 


ADCMD_WAITCYCLE 


This is a single-channel command. ADCMD_WAITCYCLE is replied to when the current cycle 
has completed, that is, after the current CMD_WRITE command has reached the end of the 
current waveform it is playing. If there is no CMD_WRITE in progress, it returns immediately. 


CMD_STOP 


This command stops the current write cycle immediately. If there are no CMD_WRITEs in 
progress, it sets a flag so any future CMD_WRITEs are queued up and do not begin processing 
(playing). 
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CMD_START 


CMD_START undoes the CMD_STOP command. Any cycles that were stopped by the 
CMD_STOP command are actually lost because of the impossibility of determining exactly 
where the DMA ceased. If the CMD_WRITE command was playing two cycles and the first one 
was playing when CMD_STOP was issued, the first one is lost and the second one will be 
played. 


This command is also useful when you are playing the same wave form with the same period 
out of multiple channels. If the channels are stopped, when the CMD_WRITE commands are 


issued, CMD_START exactly synchronizes them, avoiding cancellation and distortion. When 
channels are allocated, they are effectively started by the CMD_START command. 


CMD_READ 


CMD_READ is a single-channel command. Its only function is to return a pointer to the 
current CMD_WRITE command. It enables you to determine which request is being processed. 


Example Programs 


STEREO SOUND EXAMPLE 


This program demonstrates allocating a stereo pair of channels using the allocation /arbitration 
commands. For simplicity, it uses no hardware control commands and writes directly to the 
hardware registers. To prevent another task from stealing the channels before writing to the 
registers, it locks the channels. 
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* Stereo Sound Example 
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* Sam Dicker 

* 3 December 1985 

* (created: 17 October 1985) 
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/* If you are using the Amiga C compiler, turn off stack-checking 
* in phase 2, e.g., ‘“‘Ic2 -v filename.q.”’ 


, 


#include ”exec/types.h” 
#include ”exec/memory.h” 
#include ” hardware/custom.h” 
#include ”hardware/dmabits.h” 
#include ” libraries/dos.h” 

# include ”devices/audio.h” 


/* audio channel assignment */ 
#define LEFTOB 
#define RIGHTOB 
#define RIGHT1B 
#define LEFTIB 
#define LEF TOF 
#define RIGHTOF 
#define RIGHTIF 
#define LEFTIF 


corr WOK WN — CO 


/* used by example sound */ 
#define WAVELENGTH 2 
#define CLOCK 3579545 
#define LEFTFREQ 50.0 
#define RIGHTFREQ 50.1 
#define MAXVOLUME 64 
#define SOUNDPREC -40 


extern struct MsgPort *CreatePort(); 
extern struct AudChannel aud| J; 


extern UWORD dmacon; 


/* four possible stereo pairs */ 


UBYTE allocationMap| | = { 
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} 


LEFTOF | RIGHTOF, 
LEFTOF | RIGHTIF, 
LEFTIF | RIGHTOF, 
LEFTIF | RIGHTIF 


struct IOAudio *alloclIOB = 0; /* used by cleanUp to determine 


* what needs to be ’cleaned up’ */ 


struct IOAudio *lockIOB = 0; 
struct Device *device = 0; 
struct MsgPort *port = 0; 
BYTE *squareWaveData — 0; 


main() 


{ 


UBYTE channels; 
struct AudChannel *leftRegs, «rightRegs; 


/* allocate I/O blocks from chip public memory and initialize to zero */ 


if (((allocIOB = (struct IOAudio *)AllocMem(sizeof(struct I[OAudio), 
MEMF_PUBLIC | MEMF_CLEAR)) == 0) || 
((lockKIOB = (struct IOAudio *)AllocMem(sizeof(struct [OAudio), 
MEMF_PUBLIC | MEMF_CLEAR)) == 0)) 
cleanUp(” Out of memory”); 


/* open the audio device */ 


if (OpenDeviceiAUDIONAME, 0, allocIOB, 0) != 0) 
cleanUp(” Cannot open audio device”); 
device = alloclIOB- >10a_Request.io_Device; 


/* initialize I/O block for channel allocation */ 


alloclOB- >ioa_Request.io_Message.mn_Node.]In_Pri = SOUNDPREC; 
if ((port = CreatePort(”sound example”, 0)) == 0) 
cleanUp(” Cannot create message port” ): 
alloclOB- >ioa_Request.io_Message.mn_ReplyPort = port; 
allocIOB- >ioa_Request.io_Command = ADCMD_ALLOCATE; 


/* if no channel is available immediately, abandon allocation */ 
alloclOB- > i0a_Request.io_Flags = ADIOF_NOWAIT; 
alloclOB- >ioa_Data = allocationMap; 

allocIOB->ioa_Length = sizeof(allocationMap); 
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/* allocate channels now. Alternatively, ADCMD_ALLOCATE could have been 
* preformed when audio was first OpenDevice’d by setting up 1oa_Data and 
* ioa_Length before OpenDevice’ing */ 


BeginIO(allocIOB); 
if (WaitIO(allocIOB)) 
cleanUp(” Channel allocation failed” ); 


/* initialize I/O block for to lock channels */ 


lockIOB- > ioa_Request.io_Message.mn_ReplyPort = port; 
lockIOB- > ioa_Request.io_Device = device; 


/* one lock command to lock both channels */ 

lockIOB- > ioa_Request.io_Unit = alloclIOB->10a_Request.io_Unit; 
lockIOB- > ioa_Request.io_Command = ADCMD_LOCK; 
lockIOB- >i0a_AllocKey = allocIOB->ioa_AllocKey; 


/* lock the channels */ 
SendIO(lJockIOB); 


/* if lock returned there is an error */ 


if (CheckIO(lockIOB)) 


/* the channel must have been stolen */ 
cleanUp(” Channel stolen” ); 


/* compute the hardware register addresses */ 


channels = (ULONG)(allocIOB- > ioa_Request.io_Unit); 
leftRegs = (channels & LEFTOF) ? &aud|LEFTOB] : &aud|LEFT1B); 
rightRegs = (channels & RIGHTOF) ? &aud{|RIGHTOB] : &aud[RIGHT 1B}; 


/* allocate waveform memory from chip-addressable ram. AllocMem always 


* allocates memory on a word boundary which is necessary for audio 
* waveform data */ 


if ((squareWaveData = (BYTE *)AllooMem(WAVELENGTH, MEMF_CHIP)) == 0) 
cleanUp(” Out of memory” ); 


/* a two cycle square wave (how complex!) */ 


squareWaveData|0| = 127; 
squareWaveData|1| = -127; 
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/* these registers are described in detail in the Amiga Hardware Manual */ 


/* write-only hardware registers must be loaded separately. 

* <regl > = <reg2> = <data> may not work with some compilers */ 
leftRegs- >ac_ptr = (UWORD *)squareWaveData; 

rightRegs->ac_ptr = (UWORD +*)squareWaveData:; 

leftRegs- >ac_len = WAVELENGTH / 2; 

rightRegs- >ac_len = WAVELENGTH / 2; 


/* a slightly different frequency is used in each channel to make the 
* sound a bit more interesting */ 


leftRegs->ac_per = CLOCK / LEFTFREQ / WAVELENGTH; 
rightRegs->ac_per = CLOCK / RIGHTFREQ / WAVELENGTH; 


leftRegs- >ac_vol = MAXVOLUME:;: 
rightRegs- >ac_vol = MAXVOLUME; 
dmacon = DMAF_SETCLR | channels << DMAB_AUDO; 


/* play sound until the user press CTRL-C or lock is replied*/ 


puts(” Press CTRL-C to stop”); 
putchar(0); 
while(Wait(SIGBREAKF_CTRL_C | 1 << port->mp_SigBit) != SIGBREAKF_CTRL_C) 


/* each time the port signals, check if lock is replied 
+ (a signal is not guaranteed to be valid) */ 


if (CheckIO(lockIOB)) { 
puts(” Channel stolen”); 
break; 


} 


/* free any allocated audio channels. In this instance explicitly 
* performing the ADCMD_FREE command is unnecessary. CloseDevice’ing 
* with allocIOB performs it and frees the channels automatically */ 


allocIOB- > ioa_Request.io_Command = ADCMD_FREE; 
DoIO(allocIOB); 


/* free up resources and exit */ 
cleanUp(””); 
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/* print an error message and free allocated resources */ 


cleanU p( message) 
TEXT *message; 
{ 
puts( message); 
if (squareWaveData != 0) 
FreeMem(squareWaveData, WAVELENGTH); 
if (port != 0) 
DeletePort(port); 
if (device != 0) 
CloseDevice(allocIOB); 
if (lockIOB != 0) 
FreeMem(lockIOB, sizeof(struct IOAudio)); 
if (allocIOB != 0) 
FreeMem(allocIOB, sizeof(struct IOAudio)); 
exit(); 


DOUBLE-BUFFERED SOUND SYNTHESIS EXAMPLE 


This program demonstrates double-buffered writing to an audio channel using the hardware 
control commands. This technique can be used to synthesize sound in ‘‘real-time.’’ This pro- 


gram uses the mouse as a simple input device; to keep the example simple, the program directly 
reads the mouse register. 


Real-time synthesis code should always be written in the fastest assembly language possible 
(unlike this example) and should try to precompute as much data as possible. In this example, 
a sine wave look-up table is precomputed. Then, while the sound is being played, the table is 
scanned at a rate dependent on a variable (frequency) and the scanned values are copied into 
temporary buffers. This frequency variable is modified by mouse movement, effectively making 
the mouse a pitch control. In a ‘“‘real” program, because pitch is the only parameter being con- 
trolled, it would be much more efficient to modify the “period’’ and play one fixed sine-wave 
waveform buffer (or one waveform for each octave). 


Two temporary buffers are used. One must be computed and sent to the audio device before 
the other one has finished playing. Otherwise, the audio device turns off the sound, making a 


pop. This program runs in software interrupts to make sure that it gets adequate processor 
time to avoid this problem. 
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/* If you are using the Amiga C compiler, turn off stack-checking 
* in phase 2, e.g., ‘“‘Ic2 -v filename.q.” 

+) 

#include ”exec/types.h” 

#include ”exec/memory.h” 

#include ”exec/interrupts.h” 

#-include ”exec/errors.h” 

#include ”hardware/custom.h” 

#include ” libraries/dos.h” 

#include ” devices /audio.h” 


#define BUFFERSIZE 250 

#define SINETABLEPOWER2 — 10 

#define SINETABLESIZE (1 << SINETABLEPOWER2) 
#define SINETABLESTEP (2 * 3.141593 / SINETABLESIZE) 


/* mouse register addresses * / 
#define XMOUSEREG (*((BYTE *)&joyOdat + 1)) 
#define YMOUSEREG (-(+(BYTE *)&joyOdat)) 


extern struct MsgPort *CreatePort(); 
extern struct Library *OpenLibrary(); 
extern struct Task *FindTask(); 
extern UWORD joyOdat; 


/* channel allocation map */ 
UBYTE allocationMap| | = { 1, 8, 2, 4 }; 


struct Library *MathBase = 0; /* used by cleanUp to determine 
* what needs to be ’cleaned up’ */ 

struct MsgPort *allocPort = 0; 

struct IOAudio *alloclOB = 0; 

struct Device *device = 0; 

struct Interrupt *interrupt = 0; 

struct MsgPort *soundPort = 0; 

BYTE *buffer|2} = { 0 }; 
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struct IOAudio *soundIOB/2] = { 0 }; 


int newBuffer(); 

UBYTE sineTable[SINETABLESIZE]; 
ULONG angle = 0; 

ULONG frequency = 0x2000000; 
BYTE last YMouse; 


main() 

{ 
int 1; 
FLOAT sine = 0.0; 
FLOAT cosine = 1.0; 


/* open the math library */ 


if ((MathBase = OpenLibrary(” mathffp.library”, 0)) == 0) 
cleanUp(” Cannot open math library”); 


/* generate the sine lookup table */ 
for (1 = 0;1 < SINETABLESIZE; ++i) { 


/* generate table values between -128 and 127 */ 
sineTable[i] = 127 * sine + 0.5; 


/* compute the next point in the table. The table could have been 

* computed by calling the ’sin’ function for each point, but this 

* method is a little faster where great accuracy is not required */ 

sine += SINETABLESTEP * (cosine -= SINETABLESTEP * sine); 
} 


/* read the starting mouse count */ 
last YMouse = YMOUSEREG; 


/* initialize I/O block to allocate a channel when the audio device is OpenDevice’d */ 


if ((allocPort = CreatePort(”sound example”, 0)) == 0) 
cleanUp(” Cannot create reply port”); 
if ((allocIOB = (struct IOAudio *)AllocMem(sizeof(struct IOAudio), 
MEMF_PUBLIC | MEMF_CLEAR)) == 0) 
cleanUp(” Out of memory”); 


/* allocation precedence */ 
alloclOB- > ioa_Request.io_Message.mn_Node.]n_Pri = -40; 


) 
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alloclOB- >10a_Request.io_Message.mn_ReplyPort = allocPort; 


/* allocate from any channel */ 
allocIOB- >i0a_Data = allocationMap; 
alloclOB->ioa_Length = sizeof(allocationMap); 


/* open the audio device with channel allocation and check for errors */ 


switch (OpenDevice(AUDIONAME, 0, allocIOB, 0)) { 
case IOERR_OPENFAIL: 

cleanUp(” Cannot open audio device”); 
case ADIOERR_ALLOCFAILED: 


cleanUp(” Cannot allocate audio channel”); 
device = alloclOB- >1i0a_Request.io_Device; 
/* initialize the software interrupt structure */ 


if (interrupt = (struct Interrupt *)AllocMem(sizeof(struct Interrupt), 
MEMF_CLEAR | MEMF_PUBLIC)) == 0) 
cleanUp(” Out of memory”); 
interrupt->is_Code = (VOID (+*)())newBuffer; 


/* initialize the reply port for CMD_WRITE’s to generate software interrupts */ 


if ((soundPort = (struct MsgPort *)AllocMem(sizeof(struct MsgPort), 
MEMF_CLEAR | MEMF_PUBLIC)) == 0) 
cleanUp(” Out of memory”); 
soundPort->mp_Flags = PA_SOFTINT; 
soundPort->mp_SigTask = (struct Task *)interrupt; 
soundPort->mp_Node.In_Type = NT_MSGPORT; 
NewList(&soundPort->mp_MsgList); 


/* initialize both I/O blocks for the CMD_WRITES */ 
for (i = 0;1 < 2; ++) { 
/* allocate waveform memory from chip addressable ram. AllocMem 
* always allocates memory on a word boundary which is necessary 
* for audio waveform data */ 
if ((buffer[i] = (BYTE *)AllocMem(BUFFERSIZE, MEMF_CHIP)) 
cleanUp(” Out of memory”); 


if ((soundIOB|i] = (struct IOAudio *)AllocMem(sizeof(struct IOAudio), 
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} 


} 


MEMF_PUBLIC | MEMF_CLEAR)) == 0) 
cleanUp(” Out of memory”); 
soundIOB(il- > ioa_Request.io_Message.mn_ReplyPort = soundPort; 
soundIOB|i|- >ioa_Request.io_Device = device; 
soundIOB\|i]- >ioa_Request.io_Unit = alloclOB- > ioa_Request.io_Unit; 
soundIOB|i]- >ioa_Request.io_Command = CMD_WRITE; 


/* load the volume and period registers */ 
soundIOB|i]- >ioa_Request.io_Flags = ADIOF_PERVOL; 


soundIOB(i|- >ioa_AllocKey = allocIOB->ioa_AllocKey; 
soundIOB(|i|->ioa_Data = buffer|i]; 
soundIOB|i|->ioa_Length = BUFFERSIZE; 


/* some arbitrary period and volume */ 


soundIOB\|i|- >ioa_Period = 200; 
soundIOB|i|- >ioa_Volume = 64; 


/* play one cycle of each buffer, then reply */ 
soundIOB|i]- >ioa_Cycles = 1; 


/* this really ” primes the pump” by causing the reply port 
* to generate a software interrupt and write the first buffers */ 
Reply Msg(soundIOBIi}); 


/* wait for CTRL-C to stop the program */ 


puts(” Press CTRL-C to stop”); 
putchar(0); 
Wait(SIGBREAKF_CTRL_C); 


/* free up resources and exit */ 
cleanUp(””); 


/* print an error message and free allocated resources */ 


cleanUp(message) 
TEXT *message; 


{ 


int 1; 


puts( message); 
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} 


if (device != 0) 


/* CloseDevice’ing with ’allocIOB’ preforms an ADCMD_FREE on any 

* channel allocated with ’alloclOB’s ioa_AllocKey. ADCMD_FREE 

* performs a CMD_RESET, which performs a CMD_FLUSH, which AbortIO’s 
* any CMD_WRITES to those channels */ 

CloseDevice(allocIOB); 


for (1 = 0;1 < 2; ++i) { 
if (soundIOB|i}) 
FreeMem(soundIOB|il, sizeof(struct IOAudio)); 
if (buffer|i]) 
FreeMem(buffer|i]|, BUFFERSIZE); 
} 


if (soundPort) 

FreeMem(soundPort, sizeof(struct MsgPort)); 
if (interrupt) 

FreeMem(interrupt, sizeof(struct Interrupt)); 
if (allocIOB) 

FreeMem(allocIOB, sizeof(struct IOAudio)); 
if (allocPort) 

DeletePort(allocPort, sizeof(struct MsgPort)); 
if (MathBase) 

CloseLibrary(MathBase); 
exit(); 


/* software interrupt server code */ 


newBuffer() 


{ 


int 1; 

struct IOAudio *i0a:; 

BYTE *buffer; 

BYTE mouseChange, cur Y Mouse; 
ULONG newF reg; 


/* get I/O block from reply port */ 
ioa = (struct [OAudio *)GetMsg(soundPort); 


/* check if there really was an I/O block on the port and if there are no 

* errors. An error would indicate either the channel was aborted from 

+ being stolen IOERR_ABORTED), it was stolen before the write was 

* performed and had the wrong allocation key (ADIOF_NOALLOCATION), or it 
* was aborted by being CloseDevice’d. In any case, if there is an error do 
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* not send the next write. The program will just wait around silently */ 
if (ioa && ioa- >ioa_Request.io_Error == 0) { 
/* determine how far the mouse has moved */ 


curYMouse = YMOUSEREG; 
mouseChange = curY Mouse - last YMouse; 
last YMouse = curY Mouse; 


/* modify the frequency proportionally */ 
newF req = frequency + mouseChange * (frequency >> 6); 


/* limit the frequency range */ 


if (newFreq > 0x800000 && newFreq < 0x40000000) 
frequency — newF req; 


/* scan the table and copy each new sample into the audio waveform buffer */ 
for (i = 0, buffer = ioa->ioa_Data; 1 < BUFFERSIZE; +++) 
+buffer++ = sineTable|(angle += frequency) >> 
(32 - SINETABLEPOWER2)|: 


/* send the write I/O block */ 
BeginIO(ioa); 
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Chapter 6 


Timer Device 


Introduction 


The Amiga timer device provides a general time-delay capability. It can signal you when at 
least a certain amount of time has passed. Because the Amiga is a multitasking system, the 
timer device cannot guarantee that exactly the specified amount of time has elapsed. 


To use a timer device you open up a channel of communication to the device and send the dev- 
ice a message saying how much time should elapse. At the end of that time, the device returns 
a message to you stating that the time has elapsed. 
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Timer Device Units 


There are two units in the timer device. One uses the vertical blank interrupt for its ‘‘tick” and 
is called UNIT_VBLANK. The other uses a programmable timer in the 8520 CIA chip and is 
called UNIT_MICROHZ. These are the names you use when calling OpenDevice(). The 
examples at the end of the chapter demonstrate how you call OpenDevice(). 


The VBLANK timer unit is very stable and has a precision comparable to the vertical blanking 
time, that is, +/- 16.67 milliseconds. When you make a timing request, such as “signal me in 21 
seconds,” the reply will come in 21 +/- .017 seconds. This timer has very low overhead and 
should be used for all long duration requests. 


The MICROHZ timer unit uses the built-in precision hardware timers to create the timing inter- 
val you request. It accepts the same type of command—‘“‘signal me in so many seconds and 
microseconds.” The microhertz timer has the advantage of greater resolution than the vertical 
blank timer, but it has less accuracy over comparable periods of time. The microhertz timer 


also has much more system overhead. It is primarily useful for short burst timing for which 
critical accuracy is not required. 


Specifying the Time Request 


Both timer units have identical external interfaces. Time is specified via a timeval structure. 


struct timeval { 
ULONG tv_secs; 
ULONG tv_micro; 


bs 


The time specified is measured from the time the request is posted. For example, you must post 
a timer request for 30 minutes, rather than for a specific time such as 10:30 p.m. The micro 
field is the number of microseconds in the request. Logically, seconds and microseconds are con- 


catenated by the driver. The number of microseconds must be ‘‘normalized;” it should be a 
value less than one million. 


The primary means of specifying a requested time is via a timeRequest structure. A time 
request consists of an [ORequest structure followed by a timeval structure, as shown below. 
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struct timeRequest { 
struct [ORequest tr_node; 
struct timeval tr_time; 


3 


Note that the timer driver does not use a “‘standard extension” TORequest block. It only uses 
the base [ORequest structure. When the specified amount of time has elapsed, the driver will 
send the IORequest back via ReplyMsg() (the same as all other drivers). This means that 
you must fill in the ReplyPort pointer of the IJORequest structure if you wish to be signaled. 


When you submit a timer request, the driver destroys the values you have provided in the 
timeval structure. This means that you must reinitialize the time specification before reposting 


the [ORequest. 


Multiple requests may be posted to the timer driver. For example, you can make three time 
requests in a row to the timer, specifying: 


Signal me in 20 seconds (request 1) 
Signal me in 30 seconds (request 2) 
Signal me in 10 seconds (request 3) 


As the timer queues these requests, it changes the time values and sorts the timer requests to 
service each request at the requested interval, resulting effectively in the following order: 


(request 3) in now+10 seconds 
(request 1) 10 seconds after request 3 is satisfied 
(request 2) 10 seconds after request 1 is satisfied 


A sample timer program is given at the end of this chapter. 


Opening a Timer Device 


To gain access to a timer unit, you must first open that unit. This is done by using the system 
command OpenDevice(). A typical C-language call is shown below: 


struct timereg timer_request_block 
error = OpenDevice(TIMERNAME, unit_number,timer_request_block,0); 
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The parameters shown above are as follows: 


TIMERNAME 
This is a define for the null-terminated string, currently ‘“‘timer.device.”’ 


unit_number 


This indicates which timer unit you wish to use, either UNIT_VBLANK or 
UNIT_MICROHZ as defined in ‘‘Timer Device Units” above. 


timer_request_block 
This is the address of an I[ORequest data structure that will be used later to communi- 


cate with the device. The OpenDevice() command will fill in the unit and device 
fields of this data structure. 


Adding a Time Request 


You add a timer request to the device by passing a correctly initialized I/O request to the timer. 
The code fragment below demonstrates a sample request: 


set_timer(seconds,microseconds) 
ULONG seconds, microseconds; 


{ 
timermsg- >io_Command = TR_ADDREQUEST; 
timermsg- >tr_time.tv_secs = seconds; 
timermsg- >tr_time.tv_micro = microseconds; 
DolIO(timermsg); 


} 


Note: Using DoIO() here puts your task to sleep until the time request has been satisfied (see 
the sample program at the end of the chapter). 


If you wish to send out multiple time requests, you have to create multiple request blocks (refer- 
enced here as “‘timermsgs’’) and then use SendIO() to transmit each to the timer. 


Closing a Timer 


After you have finished using a timer device, you should close it: 
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CloseDevice(timermsg); 
Additional Timer Functions and Commands 


There are two additional timer commands (accessed as standard device commands, using an 


IORequest block as shown above) and three additional functions (accessed as though they were 
library functions). 


The additional timer commands are as follows: 
o TR_GETSYSTIME — get the system time 
o TR_SETSYSTIME — set the system time 
The additional timer library-like functions are: 
o SubTime( Dest, Source ) — subtract one time request from another 
o AddTime( Dest, Source ) — add one time request to another 


o result = CmpTime( Dest, Source) — compare the time in two time requests 


SYSTEM TIME 


The “system timer’’ is unrelated to the system time as it appears in the DateStamp command 


of AmigaDOS. It is provided simply for the convenience of the developer and is utilized by 
Intuition. 


The command TR_SETSYSTIME sets the system’s idea of what time it is. The system starts 
out at time “‘zero’’ so it is safe to set it forward to the “real’’ time. However, care should be 


taken when setting the time backwards. System time is specified as being monotonically 
increasing. 


The time is incremented by a special power supply signal that occurs at the external line fre- 
quency. This signal is very stable over time, but it can vary by several percent over short 
periods of time. System time is stable to within a few seconds a day. In addition, system time 
is changed every time someone asks what time it is using TR_GETSYSTIME. This way the re- 


turn value of the system time is unique and unrepeating. This allows system time to be used as 
a unique identifier. 
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Note: The timer device sets system time to zero at boot time. AmigaDOS will set the system 
time when it reads in the boot disk, if it has not already been set by someone else (more exactly, 
if the time is less than 86,400 seconds [one day]|). AmigaDOS sets the time to the last 
modification time of the boot disk. The time device does not interpret system time to any phy- 
sical value. AmigaDOS treats system time relative to midnight, 1 January 1978. 


Here is a program that can be used to inquire the system time. Instead of using the Exec sup- 
port function CreateStdIO() for the request block, the block is initialized “correctly” for use 


as a timeval request block. The command is executed by the timer device and, on return, the 
caller can find the data in his request block. 


/* getsystime.c - get system time */ 


#include ”exec/types.h” 
#include ”exec/lists.h” 
#include ”exec/nodes.h” 
#include ”exec/ports.h” 
#include ”exec/io.h” 
#include ”exec/devices.h” 
#include ” devices/timer.h” 


#:define msgblock tr.tr_node.io_Message 
struct timerequest tr; 


main() 


int error; 

error = OpenDevice(TIMERNAME,UNIT_MICROHZ,&tr,0); 
msgblock.mn_Node.In_Type = NT_MESSAGE; 
msgblock.mn_Node.In_Pri = 0; 

msgblock.mn_Node.In_Name = NULL; 
msgblock.mn_ReplyPort = NULL; 


tr.tr_node.io_Command = TR_GETSYSTIME; 
DolO(&tr); 


printf(”\nSystem Time is:\n”); 

printf (”’Seconds Microseconds\n” ); 

printf (”"%10ld %10ld\n” ,tr.tr_time.tv_secs, tr.tr_time.tv_micro); 
CloseDevice(&tr); 


} /* end of main */ 
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USING THE TIME ARITHMETIC ROUTINES 


As indicated above, the time arithmetic routines are accessed in the timer device structure as 
though it were a routine library. To use them, you create an [ORequest block and open the 
timer. In the T[ORequest block is a pointer to the device’s base address. This address is need- 
ed to access each routine as an offset—for example, LWVOAddTime, _LVOSubTime, 


_LVOCmpTime—from that base address. (See the “(Device Summaries” appendix for these 
commands.) 


There are C-language interface routines in amiga.lib that perform this interface task for you. 
They are accessed through a variable called TimerBase. You prepare this variable by the fol- 
lowing method (this is only a partial example): 


struct timeval timel, time2, time3; 


SHORT result; 


struct Device *TimerBase; /* declare the interface variable */ 
TimerBase = timermsg- > Device; 


/* now that TimerBase is initialized, it is permissible to call 
* the time-comparison or time-arithmetic routines * / 


timel.tv_secs = 3; timel.tv_micro — 0; /* 3.0 seconds */ 
time2.tv_secs = 2; time2.tv_micro =— 500000; /* 2.5 seconds */ 
time3.tv_secs = 1; time2.tv_micro = 900000; /* 1.9 seconds */ 


/* result of this example is +1 ... first parameter has 
* greater time value than second parameter 
+] 


result = CmpTime( &timel, &time2 ); 


/* add to timel the values in time2 */ 

AddTime( &timel, &time2); 

/* subtract values in time3 from the value currently in timel. 
* Results in timel. */ 

SubTime( &timel1, &time3); 
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WHY USE TIME ARITHMETIC? 


As mentioned earlier in this section, because of the multitasking capability of the Amiga, the ti- 
mer device can provide timings that are at least as long as the specified amount of time. If you 
need more precision than this, using the system timer along with the time arithmetic routines 


can at least, in the long run, let you synchronize your software with this precision timer after a 
selected period of time. 


Say, for example, that you select timer intervals so that you get 161 signals within each 3- 
minute span. Therefore, the timeval you would have selected would be 180/161, which comes 
out to 1 second and 118,012 microseconds per interval. Considering the time it takes to set up 
a call to set_timer and delays due to task-switching (especially if the system is very busy) it is 
possible that after 161 timing intervals, you may be somewhat beyond the 3-minute time. Here 
is a method you can use to keep in sync with system time: 

1. Begin. 

2. Read system time; save it. 


3. Perform your loop however many times in your selected interval. 


4. Read system time again, and compare it to the old value you saved. (For this example, 
it will be more or less than 3 minutes as a total time elapsed.) 


5. Calculate a new value for the time interval (timeval); that is, one that (if precise) 


would put you exactly in sync with system time the next time around. Timeval will 


be a lower value if the loops took too long, and a higher value if the loops didn’t take 
long enough. 


6. Repeat the cycle. 


Over the long run, then, your average number of operations within a specified period of time 
can become precisely what you have designed. 


Sample Timer Program 


Here is an example program showing how to use a timer device. 
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/* Simple Timer Example Program: 

* 

* Includes dynamic allocation of data structures needed to communicate 
* with the timer device as well as the actual device I/O 


+ 


#include ”exec/types.h” 
#include ” exec/nodes.h” 
#include ” exec/lists.h” 
#include ”exec/memory.h” 
#include ”exec/interrupts.h” 
#include ”exec/ports.h” 
#include ”exec/libraries.h” 
#include ”exec/tasks.h” 
#include ”exec/io.h” 
#include ”exec/devices.h” 
#include ” devices /timer.h” 


APTR TimerBase; /* to get at the time comparison functions */ 


/* manifest constants -- ”never will change” */ 
#-define SECSPERMIN (60) 

#define SECSPERHOUR (60*60) 
#define SECSPERDAY (60*60*24) 


extern struct timerequest *CreateTimer(); 


main() 


{ 


/* save what system thinks is the time.... we’ll advance it temporarily */ 
LONG seconds; 

struct timerequest *tr; 

struct timeval oldtimeval; 

struct timeval mytimeval; 

struct timeval currentval; 


printf(” Oimer testO); 


/* sleep for two seconds */ 
currentval.tv_secs = 2; 

currentval.tv_micro = 0; 

TimeDelay( &currentval, UNIT_VBLANK ); 
printf( ” After 2 seconds delay0O ); 
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/* sleep for four seconds */ 
currentval.tv_secs = 4; 

currentval.tv_micro = Q; 

TimeDelay( &currentval, UNIT_VBLANK ); 
printf( ” After 4 seconds delay0 ); 


/* sleep for 500,000 micro-seconds = 1/2 second */ 
currentval.tv_secs = 0; 

currentval.tv_micro = 500000; 

TimeDelay( &currentval, UNIT_MICROHZ ); 
printf( ” After 1/2 second delay0 ); 


printf(”0 ); 

(void) Execute( ”date”, 0, 0 ); 

printf( ”0 ); 

GetSysTime( &oldtimeval ); 

printf( ”Current system time is %ld current seconds0, 
oldtimeval.tv_secs ); 

printf(” Setting a new system time0); 


seconds = 1000 * SECSPERDAY + oldtimeval.tv_secs; 


SetNewTime( seconds ); 
/* (if user executes the AmigaDOS DATE command now, he will 
* see that the time has advanced something over 1000 days */ 


printf( ”0 ); 
(void) Execute( ”date”, 0, 0 ); 


printf(”0 ); 


/* added the microseconds part to show that time keeps 

* increasing even though you ask many times in a row */ 

GetSysTime( &mytimeval ); 

printf( ” Original system time is %1d.%061d0, 
mytimeval.tv_secs, mytimeval.tv_micro ); 


GetSysTime( &mytimeval ); 


printf( ”First system time is %ld.%061d0, 
mytimeval.tv_secs, mytimeval.tv_micro ); 
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} 


GetSysTime( &mytimeval ); 
printf( ”Second system time is %1ld.%061d0, 
mytimeval.tv_secs, mytimeval.tv_micro ); 


printf( ”Resetting to former time ); 
SetNewTime( oldtimeval.tv_secs }); 


GetSysTime( &mytimeval ); 
printf( ”Current system time is %1d.%061d0, 
mytimeval.tv_secs, mytimeval.tv_micro ); 


/* just shows how to set up for using the timer functions, does not 

* demonstrate * the functions themselves. (TimerBase must have a 

+ legal value before AddTime, SubTime or CmpTime are performed. */ 
tr = CreateTimer( UNIT_MICROHZ ); 

TimerBase = (APTR)tr->tr_node.io_Device; 


/* and how to clean up afterwards */ 
TimerBase = (APTR)(-1); 
DeleteTimer( tr ); 


extern struct MsgPort *CreatePort(); 
extern struct [ORequest *CreateExtIO(); 


struct timerequest * 
CreateTimer( unit ) 
ULONG unit; 


{ 


/* return a pointer to a time request. If any problem, return NULL */ 
int error; 


struct MsgPort *timerport; 
struct timerequest *timermsg; 


timerport = CreatePort( 0, 0 ); 
if( timerport =— NULL ) 


return( NULL ); 
j 


timermsg = (struct timerequest *) 
CreateExtIO( timerport, sizeof( struct timerequest ) ); 
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if( timermsg == NULL ) { 
return( NULL ); 
} 


error = OpenDevice( TIMERNAME, unit, timermsg, 0 ); 
if( error != 0 ) 


DeleteTimer( timermsg ); 
return( NULL ); 


} 


return( timermsg ); 


} 


/* more precise timer than AmigaDOS Delay() */ 
TimeDelay( tv, unit ) 

struct timeval *tv; 

int unit; 

{ 


struct timerequest *tr; 


/* get a pointer to an initialized timer request block */ 
tr = CreateTimer( unit ); 


/* any nonzero return says timedelay routine didn’t work. */ 


if( tr === NULL ) return( -1 ); 
WaitForTimer( tr, tv ); 


/* deallocate temporary structures */ 
DeleteTimer( tr ); 
return( 0 ); 


int 
WaitForTimer( tr, tv ) 
struct timerequest *tr; 
struct timeval *tv; 
{ 
tr- >tr_node.io_Command = TR_ADDREQUEST; /* add a new timer request */ 


/* structure assignment */ 
tr- >tr_time = *tv; 


/* post request to the timer -- will go to sleep till done */ 
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} 


int 


DolO( tr ); 


SetNewTime( secs ) 
LONG secs; /* seconds since 1 Jan 78 */ 


{ 


struct timerequest *tr; 
tr = CreateTimer( UNIT_MICROHZ ); 


/* non zero return says error */ 
if( tr == 0 ) return( -1 ); 


tr- >tr_node.io_Command = TR_SETSYSTIME; 
tr- >tr_time.tv_secs = secs; 
tr- >tr_time.tv_micro = 0; 


DolO( tr ); 
DeleteTimer(tr); 
return(0); 

} 

int 

GetSysTime(tv) 


struct timeval *tv; 


{ 


struct timerequest *tr;, 
tr = CreateTimer( UNIT_MICROHZ ); 


/* non zero return says error */ 
if( tr == 0 ) return( -1 ); 


tr- >tr_node.io_Command = TR_GETSYSTIME; 
DolO( tr ); 


/* structure assignment */ 
*tv — tr->tr_time; 


DeleteTimer( tr ); 
return( 0 ); 
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int 
DeleteTimer( tr ) 
struct timerequest *tr; 


{ 


struct MsgPort *tp; 


if( tr != 0 ) 
tp = tr->tr_node.io_Message.mn_ReplyPort; 
if(tp !== 0) { 
DeletePort(tp); 


} 


CloseDevice( tr ); 
DeleteExtIO( tr, sizeof(struct timerequest) ); 
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Chapter 7 


Trackdisk Device 


Introduction 


The Amiga trackdisk device directly drives the disk, controls the disk motors, reads raw data 
from the tracks, and writes raw data to the tracks. Normally, you use the AmigaDOS functions 
to write or read data from the disk. The trackdisk driver is the lowest-level software access to 
the disk data and is used by AmigaDOS to get its job done. The trackdisk device supports the 
usual commands such as CMD_WRITE and CMD_READ. In addition, it supports an extended 


form of these commands to allow additional control over the disk driver. 
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The trackdisk device can queue up command sequences so that your task can do something else 
while it is waiting for a particular disk activity to occur. If several sequenced write commands 
are queued to a disk, a task assumes that all such writes are going to the same disk. The track- 
disk driver itself can stop a command sequence if it senses that the disk has been changed, 
returning all subsequent [ORequest blocks to the caller with an error (‘“‘disk changed”’). 


When the trackdisk device is requested to provide status information for commands such as 
TD REMOVE or TD_CHANGENUM, the value is returned in the io_Actual field of the 
TORequest. 


The Amiga Floppy Disk 


The Amiga floppy disk consists of NUMHEADS (2) heads, NUMCYLS (80) cylinders, and 
NUMSECS (11) sectors per cylinder. Each sector has TD_SECTOR (512) usable data bytes 
plus TD_LABELSIZE (16) of sector label area. This gives useful space of 880K bytes plus 28K 
bytes of label area per floppy disk. 


Although the disk is logically divided up into sectors, all I/O to the disk is implemented as an 
entire track. This allows access to the drive with no interleaving and increases the useful 
storage capacity by about 20 percent. Normally, a read of a sector will only have to copy the 
data from the track buffer. If the track buffer contains another track’s data, then the buffer 
will first be written back to the disk (if it is “dirty’’) and the new track will be read in. All 


track boundaries are transparent to the user. The driver ensures that the correct track is 
brought into memory. 


The performance of the disk is greatly enhanced if you make effective use of the track buffer. 


The performance of sequential reads will be up to an order of magnitude greater than reads 
scattered across the disk. 


The disk driver uses the blitter to encode and decode the data to and from the track buffer. 
Because the blitter can access only chip memory (memory that is accessible to the special- 
purpose chips and within the lowest 512K bytes of the system, known as MEMF_CHIP to the 
memory allocator AllocMem()), all buffers submitted to the disk must be in chip memory. In 


addition, only full-sector writes on sector boundaries are supported. Note also that the user’s 
buffer must be word-aligned. 


The disk driver is based upon a standard driver structure. It has the following restrictions: 


o All reads and writes must use an io_Length that is an integer multiple of 


TD_SECTOR bytes (the sector size in bytes). 
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o The offset field must be an integer multiple of TD_SECTOR. 
o The data pointer must be word-aligned. 


o The data pointer must be in MEMF_CHIP memory. This is because the disk driver 
uses the blitter to fill the data buffer. 


o Only the 3 1/2-inch disk format is supported by the trackdisk driver. The 5 1/4-inch 
format is supported by the IBM PC emulation software. 


Trackdisk Driver Commands 


The trackdisk driver allows the following system interface functions and commands. In addition 
to the usual device commands, the trackdisk driver has a set of extended commands. 


The system interface functions are 


OpenDevice() Obtain exclusive use of a particular disk unit 
CloseDevice() Release the unit to another task 


Expunge() Remove the device from the device list 
BeginIO() Dispatch a device command; queue commands 
AbortIO() Abort a device command 


The device-specific commands are 


CMD_READ Read one or more sectors 

CMD_WRITE Write one or more sectors 

CMD_UPDATE Write out a track buffer 

CMD_CLEAR Mark a track buffer as invalid 

TD_MOTOR Turn the motor on or off 

TD_SEEK Move the head to a specific track 

TD_FORMAT Initialize one or more tracks 

TD_REMOVE Establish a software interrupt procedure for disk removal 


TD_CHANGENUM Discover the current disk-change number 
TD_CHANGESTATE _ See if there is a disk present in a drive 
TD_PROTSTATUS See if a disk is write-protected 


In addition to the device-specific commands listed above, the trackdisk driver has a number of 
extended commands. These commands are similar to their normal counterparts but have addi- 
tional features: they allow you to control whether a command will be executed if the disk has 
been changed, and they allow you to read or write to the sector label portion of a sector. 
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Extended commands take a slightly larger I/O request block, which contains information that is 
needed only by the extended command and that is ignored by the standard form of that com- 
mand. The extra information takes the form of two extra longwords at the end of the data 
structure. These commands are performed only if the change count is less than or equal to the 
one in the iotd_Count field of the command’s I/O request block. The extended commands are 
listed below: 


ETD_READ Read one or more sectors 
ETD_WRITE Write one or more sectors 
ETD_MOTOR Turn the motor on or off 
ETD_UPDATE Write out a track buffer 

ETD _CLEAR Mark a track buffer as invalid 
ETD_SEEK Move the head to a specific track 


Creating an I/O Request 


The trackdisk device, like other devices, requires that you create an I/O request message that 


you pass to the device for processing. The message contains the command and several other 
items of control information. 


Here is a program fragment that can be used to create the message block that you use for track- 
disk communications. In the fragment, the routine CreateStdIO() is called to return a pointer 
to a message block. This is acceptable for the standard form of the commands. If you wish to 
use the extended form of the command, you will need an extended form of the request block. In 
place of CreateStdIO(), you can use the routine CreateExtIO(), a listing of which appears in 
the appendixes of the Amiga ROM Kernel Reference Manual: Ezec. 


struct [OStdReq *diskreq; /* I/O request block pointer 
* for non-extended commands */ 
struct IOExtTD *diskextreq; /* I/O request block pointer 
* for extended commands */ 
struct Port *diskreqPort; /* a port at which to receive replies * / 


diskreqPort = CreatePort(” diskreq.port” ,O); 

if(diskreqPort === 0) exit(100); /* error in CreatePort() */ 

diskreq = CreateStdIO(diskreqPort); 

if(diskreq == 0) { DeletePort(diskreqPort); exit(200); } /* error in CreateStdIO() 
diskextreq = CreateExtIO(diskreqPort,sizeof(struct IOExtTD)); 

if(diskextreq == 0) { DeletePort(diskreqPort); exit(300) }; 
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The routine CreatePort() is part of amiga.léb. It returns a pointer to a Port structure that 
can be used to receive replies from the trackdisk driver. 


The routine CreateStdIO() is also in amiga.lib. It returns a pointer to an IOStdReq block 
that becomes the message you pass to the trackdisk driver to tell it the command to perform. 


The data structure IOExtTD takes the form: 


struct IOExtTD { 
struct [OStdReq iotd_Req; 
ULONG iotd_Count; 
ULONG §iotd_SecLabel; 


ie 
where 


IOStdReq 


is a standard [ORequest block that contains fields used to transmit the standard com- 
mands (explained below). 


iotd Count 

helps keep old I/O requests from being performed when the diskette has been changed. 
All extended commands treat as an error any case where the disk change counter is 
greater than iotd_Count. Any I/O request found with an iotd_Count less than the 
current change counter value will be returned with a characteristic error 
(TDERR_DiskChange) in the io_Error field of the I/O request block. This allows stale 
I/O requests to be returned to the user after a disk has been changed. The current 
disk-change counter value can be obtained by TD_CHANGENUM. 


If the user wants extended disk I/O but does not care about disk removal, then 
iotd_Count may be set to the maximum unsigned long integer value (OxFFFFFFFF). 


iotd_SecLabel 


allows access to the sector identification section of the sector header. 


Each sector has 16 bytes of descriptive data space available to it; the disk driver does 
not interpret this data. If iotd_SecLabel is null, then this descriptive data is ignored. 
If it is not null, then iotd_SecLabel should point to a series of 16-byte chunks (one for 
each sector that is to be read or written). These chunks will be written out to the 
sector’s label region on a write or filled with the sector’s label area on a read. If a 
CMD_WRITE (the standard write call) is done, then the sector label area is left 


unchanged. 
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Opening a Trackdisk Device 


To gain access to a disk unit, you must first open the unit by using the system command 
OpenDevice(). A typical C-language call is shown below: 


error = OpenDevice(TD_NAME,unit_number,disk_request_block,flags); 
where: 


TD_NAME 


is a define for the null-terminated string, currently ‘“‘trackdisk.device.”’ 


unit_number 
is the disk unit you wish to use (defined below). 


disk_request_block 
is the address of an IORequest data structure that will later be used to communicate 
with the device. The OpenDevice() command will fill in the unit and device fields of 
this data structure. 


flags 
tell how the I/O is to be accomplished. For an OpenDevice() command, this field is 
normally set to zero. 


The unit_number can be any value from 0 to 3. Unit 0 is the built-in 3 1/2-inch disk. Units 
1 through 3 represent additional 3 1/2-inch disks that may be daisy-chained from the external 
disk unit connector on the back of the Amiga. The first unit (plugged directly into the Amiga) 
is unit 1. The second unit (plugged into unit 1), is designated as unit 2. The end-unit, farthest 
electrically from the Amiga, is unit 3. 


The following are some common errors that may be returned from an OpenDevice() call. 


Device in use 
Some other task has already been granted exclusive use of this device. 


Bad untt number 
Either you have specified a unit number outside the range of 0-3 or you do not have a 
unit connected in the specified position. 


Bad device type 


You may be trying to use a 5 1/4-inch drive with the trackdisk driver. This is not 
supported. 
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Sending a Command to the Device 


You send a command to this device by initializing the appropriate fields of your IOStdReq or 
IOExtTD and then using SendIO(), DoIO(), or BeginIO() to transmit the command to the 


device. Here is an example: 


MotorOn() 

{ 
diskreq->io_Length = 1; /* 1 says turn it on */ 
diskreq- >io_Command = TD_MOTOR; 
DolO(diskreq); /* task sleep till command done */ 
return(0); 


Terminating Access to the Device 


As with all exclusive-access devices, you must close the trackdisk device when you have finished 


using it. Otherwise, the system will be unable to allocate the device to any other task until the 
system is rebooted. 


Device-specific Commands 


The device-specific commands that are supported are explained below. 


ETD_READ AND CMD_READ 


ETD_READ obeys all of the trackdisk driver restrictions noted above. ETD_READ transfers 
data from the track buffer to the user’s buffer, if and only if the disk has not been changed. If 
the desired sector is already in the track buffer, no disk activity is initiated. If the desired sec- 
tor is not in the buffer, the track containing that sector is automatically read in. If the data in 
the current track buffer has been modified, it is written out to the disk before the new track is 
read. CMD_READ does not check if the disk has been changed before executing this command. 


TRACKDISK NAME 
TRACK DISK REQUEST (NO) 
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ETD_WRITE AND CMD_WRITE 


ETD_WRITE obeys all of the trackdisk driver restrictions noted above. E’‘TD_WRITE transfers 
data from the user’s buffer to track buffer if and only if the disk has not been changed. If the 
track that contains this sector is already in the track buffer, no disk activity is initiated. If the 
desired sector is not in the buffer, the track containing that sector is automatically read in. If 
the data in the current track buffer has been modified, it is written out to the disk before the 
new track is read in for modification. CMD_WRITE does not check for disk change before per- 
forming the command. 


ETD_UPDATE AND CMD_UPDATE 


The Amiga trackdisk driver does not write data sectors unless it is necessary (you request that a 
different track be used) or until the user requests that an update be performed. This improves 
system speed by caching disk operations. The update commands ensure that any buffered data 
is flushed out to the disk. If the track buffer has not been changed since the track was read in, 
the update commands do nothing. In addition, ETD_UPDATE can make sure that the disk 
was not changed before it writes the buffer. This prevents writing the buffered data onto a 
different diskette. 


ETD_CLEAR AND CMD_CLEAR 


ETD_CLEAR marks the track buffer as invalid, forcing a reread of the disk on the next opera- 
tion. ETD UPDATE or CMD_UPDATE would be used to force data out to the disk before 
turning the motor off. ETD CLEAR or CMD_CLEAR is usually used after the disk has been 
removed, to prevent caching of data to the new diskette. ETD_CLEAR or CMD_CLEAR will 


not do an update, nor will an update command do a clear. CMD_CLEAR does not check for 
disk change. 


ETD_MOTOR AND TD_MOTOR 


TD_MOTOR is called with a standard IORequest block. The io Length field contains the 
requested state of the motor. A 1 will turn the motor on; a O will turn it off. The old state of 
the motor is returned in io_Actual. If io_Actual is zero, then the motor was off. Any other 
value implies that the motor was on. If the motor is just being turned on, the driver will delay 
the proper amount of time to allow the drive to come up to speed. Normally, turning the drive 
on is not necessary —the driver does this automatically if it receives a request when the motor 
is off. However, turning the motor off is the user’s responsibility. In addition, the standard 
instructions to the user are that it is safe to remove a diskette if and only if the motor is off 


(that is, if the disk light is off). 
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TD_FORMAT 


TD_FORMAT is used to write data to a track that either has not yet been formated or has had 
a hard error on a standard write command. TD_FORMAT completely ignores all data 
currently on a track and does not check for disk change before performing the command. 
TD_FORMAT is called with a standard I[ORequest. The io_Data field must point to at least 
one track worth of data. The io_Offset field must be track aligned, and the io_Length field 
must be in units of track length (that iss NUMSECS*TD_SECTOR ). The driver will format 
the requested tracks, filling each sector with the contents of the io_Data field. You should do a 
read pass to verify the data. The command TD_FORMAT does not check whether the disk has 
been changed before the command is performed. 


If you have a hard write error during a normal write, you may find it necessary to use the 
TD_FORMAT command to reformat the track as part of your error recovery process. 


TD_REMOVE 


TD_REMOVE is called with a standard IORequest. The APTR io_Data field points to a 
software interrupt structure. The driver will post this software interrupt whenever a disk is 
inserted or removed. To find out the current state of the disk, TD_CHANGENUM and 
TD_CHANGESTATE should be used. If TD REMOVE is called with a null io Data argu- 


ment, then disk removal interrupts are suspended. 


Status Commands 


The commands that return status on the current disk in the unit are TD_CHANGENUM, 
TD_CHANGESTATE, and TD_PROTSTATUS. 


TD_CHANGENUM 


TD_CHANGENUM returns the current value of the disk-change counter (as used by the 
extended commands—see below). The disk change counter is incremented each time the disk is 
inserted or removed. 
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TD_CHANGESTATE 


TD_CHANGESTATE returns zero if a disk is currently in the drive, and nonzero if the drive 
has no disk. 


TD_PROTSTATUS 


TD_PROTSTATUS returns nonzero if the current diskette is write-protected. All these rou- 
tines return their values in io_Actual. These routines are safe to call from an interrupt routine 
(such as the software interrupt specified in TD_REMOVE ). However, care should be taken 
when calling these routines from an interrupt. You should never Wait() for them to complete 
while in interrupt processing — it is never legal to go to sleep on the interrupt stack. 


Commands for Diagnostics and Repair 


Currently only one command, TD_SEEK, is provided for internal diagnostics and for disk 
repair. 


TD_SEEK is called with a standard [ORequest. The io_Offset field should be set to the 
(byte) offset to which the seek is to occur. TD_SEEK will not verify its position until the next 


read. That is, TD_SEEK only moves the heads; it does not actually read any data and it does 
not check to see if the disk has been changed. 


Trackdisk Driver Errors 


Table 7-1 is a list of error codes that can be returned by the trackdisk driver. When an error 
occurs, these error numbers will be returned in the io_Error field of your I[ORequest block. 
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Table 7-1: Trackdisk Driver Error Codes 


Error 
Error Name Number Meaning 

TDERR_NotSpecified 20 Error could not be determined 
TDERR_NoSecHdr 21 Could not find sector header 
TDERR_BadSecPreamble 22 Error in sector preamble 
TDERR_BadSecID 23 Error in sector identifier 
TDERR_BadHdrSum 24 Header field has bad checksum 
TDERR_BadSecSum 25 Sector data field has bad checksum 
TDERR_TooFewSecs 26 Incorrect number of sectors on track 
TDERR_BadSecHdr 27 Unable to read sector header 
TDERR_WriteProt 28 Disk is write-protected 
TDERR_DiskChanged 29 Disk has been changed 

or is not currently present 
TDERR_SeekError 30 While verifying seek position, 

found seek error 
TDERR_NoMem 31 Not enough memory to do this operation 
TDERR_BadUnitNum 32 Bad unit number 

(unit # not attached) 
TDERR_BadDriveType 33 Bad drive type 

(not an Amiga 3 1/2 inch disk) 
TDERR_DrivelnUse 34 Drive already in use 

(only one task exclusive) 
TDERR_PostReset 35 User hit reset; awaiting doom 


Example Program 


The following sample program exercises a few of the trackdisk driver commands. 


#-include ” exec /types.h” 
#include ” exec /nodes.h” 
#include ” exec /lists.h” 
#include ”exec/memory.h” 
#include ” exec /interrupts.h” 
#include ” exec /ports.h” 
#include ” exec /libraries.h” 
#include ” exec /io.h” 
#include ” exec /tasks.h” 
#include ” exec /execbase.h” 
#include ”exec/devices.h” 
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#include ” devices/trackdisk.h” 


#define TD_READ CMD_READ 
#define BLOCKSIZE TD_SECTOR 


SHORT error; 

struct MsgPort *diskport; 
struct IOExtTD *diskreq; 
BYTE diskbuffer[|BLOCKSIZE]; 
BYTE *diskdata; 

SHORT testval; 


extern struct MsgPort *CreatePort(); 
extern struct IORequest *CreateExtIO(); 


ULONG diskChangeCount; 


ReadCy|Sec(cyl, sec, hd) 
SHORT cyl, sec, hd; 


{ 


LONG offset; 


diskreq- > iotd_Req.io_Length —= BLOCKSIZE; 
diskreq- >iotd_Req.io_Data = (APTR)diskbuffer; 

/* show where to put the data when read */ 
diskreq- >iotd_Req.io_Command = ETD_READ; 

/* check that disk not changed before reading */ 
diskreq- >iotd_Count = diskChangeCount; 


/* convert from cylinder, head, sector to byte-offset value to get 
* right one (as dos and everyone else sees it)...*/ 


/* driver reads one CYLINDER at a time (head does not move for 
* 22 sequential sector reads, or better put, head does not move for 
* 2 sequential full track reads.) 


us 


offset = TD_SECTOR * (sec + NUMSECS * hd + NUMSECS * NUMHEADS ¥ cyl); 
diskreq- > iotd_Req.io_Offset = offset; 


DolO(diskreq); 
return(0); 

} 

MotorOn() 


{ 


/* TURN ON DISK MOTOR ... old motor state is returned in io_Actual */ 
diskreq- > iotd_Req.io_Length — 1; 

/* this says motor is to be turned on */ 

diskreq- >iotd_Req.io_Command —= TD_MOTOR; 

/* do something with the motor */ 

DolO(diskregq); 

printf(”\\nOld motor state was: %1d” ,diskreq- >iotd_Req.io_Actual); 
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printf(” \nio_Error value was: %1d” ,diskreq- > iotd_Req.io_Error); 
return(0); 


MotorOff() 
{ 
printf(” \n\nNow turn it off”); 
diskreq- >iotd_Req.io_Length = 0; 
/* says that motor is to be turned on */ 
diskreq- >10td_Req.io_Command = TD_MOTOR; 
/* do something with the motor */ 
DolO(diskreq); 
printf(”\nOld motor state was: %1d” ,diskreq- >iotd_Req.io_Actual); 
printf(” \nio_Error value was: %1d” ,diskreq- > iotd_Req.io_Error); 
return(0); 


} 


SeekFullRange(howmany) 
SHORT howmany; 
- 
int 1; 
for(i=0; i<howmany; i++) 
‘ 
diskreq- >iotd_Req.io_Offset = 
((NUMCYLS -1)*NUMSECS*NUMHEADS -1 ) * 512: 
/* seek to cylinder 79, head 1 */ 
diskreq- >iotd_Req.io_Command = TD_SEEK; 
DolO(diskreq); 
if(diskreq- >iotd_Req.io_Error != 0) 
printf(”\nSeek Cycle Number %ld, Error = %1d”, 
i, diskreq- > iotd_Req.io_Error); 
diskreq- >iotd_Req.io_Offset = 0; 
/* seek to cylinder 0, head 0 */ 
diskreq- >iotd_Req.io_Command = TD_SEEK; 
DolO(diskreq); 
if(diskreq- > iotd_Req.io_Error != 0) 
printf(”\nSeek Cycle Number %ld, Error = %1d”, 
i, diskreq- >iotd_Req.io_Error); 
printf(” \nCompleted a seek” ); 


} 


return(0); 


main() 
SHORT cylinder,head,sector; 


diskdata = &diskbuffer|0]; 
/* point to first location in disk buffer */ 
diskport = CreatePort(0,0); 
if(diskport == 0) exit(100); _/* error in createport */ 
diskreq = (struct IOExtTD *)CreateExtIO(diskport, sizeof(struct IOExtTD)); 
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/* make an io request block for communicating with the disk */ 
if(diskreq == 0) { DeletePort(diskport); exit(200); } 


error = OpenDevice(TD_NAME,0,diskreq,0); 
/* open the device for access, unit 0 is builtin drive */ 
printf(” \nError value returned by OpenDevice was: %1x”, error); 


/* now get the disk change value */ 

diskreq- >10td_Req.io_Command = TD_CHANGENUM; 
DolO(diskreq); 

diskChangeCount = diskreq- >iotd_Req.io_Actual; 

printf(” \nChange number for disk is currently % ld” ,diskChangeCount); 


MotorOn(); 

SeekFullRange(10); 

for(cylinder=0; cylinder< 80; cylinder++) /* tracks to test */ 
for(head—0; head <2; head++) /* number of heads to test */ 

for(sector—=0; sector<11; sector++) /* sectors to test */ 


ReadCyl]Sec(cylinder, sector, head); 
if(diskreq- >iotd_Req.io_Error != 0) 
printf(” \nError At Cyl=%ld, Sc=%1ld, Hd=% 1d, Error=% 1d”, 
cylinder,sector,head, 
diskreq >iotd_Req.io_Error); 


printf(” \nCompleted reading Cylinder=% 1d” ,cylinder); 


} 
MotorOff(); 
CloseDevice(diskreq); 


DeleteExtIO(diskreq, sizeof(struct IOExtTD)); 


DeletePort(diskport); 
} /* end of main */ 
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Chapter 8 


Console Device 


This chapter describes how you do console (keyboard and screen) input and output on the 
Amiga. The console device acts like an enhanced ASCII terminal. It obeys many of the stan- 
dard ANSI sequences as well as additional special sequences unique to the Amiga. 


Introduction 


Console I/O is tied closely to the Amiga Intuition interface; a console must be tied to a window 
that is already opened. From the Window data structure, the console device determines how 
many characters it can display on a line and how many lines of text it can display in a window 
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without clipping at any edge. 


You can open the console device many times, if you wish. The result of each open call is a new 
console unit. AmigaDOS and Intuition see to it that only one window is currently active and its 
console, if any, is the only one (with a few exceptions) that receives notification of input events, 
such as keystrokes. Later in this chapter you will see that other Intuition events can be sensed 
by the console device as well. 


Note: For this entire chapter the characters ‘“<CSI>” represent the control sequence intro- 
ducer. For output you may use either the two-character sequence ‘‘“<Esc>|” or the one-byte 
value $9B (hex). For input you will receive $9B’s. 


System Functions 


The various system functions—such as DoIO(), SendIO(), AbortIO(), CheckIO(), and so 
on—operate normally. The only caveats are that CMD_WRITE may cause the caller to wait 
internally, even with SendIO(), and a task waiting on response from a console is at the user’s 
whim. If a user never reselects that window, and the console response provides the only wake- 
up call, that task may well sleep indefinitely. 


Console I/O 


The console device may be thought of as a kind of terminal. You send character streams to the 
console device; you also receive them from the console device. These streams may be characters 
or special sequences. 


GENERAL CONSOLE SCREEN OUTPUT 


Console character screen output (as compared to console command sequence transmission) out- 
puts all standard printable characters (character values hex 20 thru 7E and AO thru FF) nor- 
mally. Many control characters such as BACKSPACE and RETURN are translated into their 
exact ANSI equivalent actions. The line-feed character is a bit different, in that it can be 
translated into a new-line character. The net effect is that the cursor moves to the first column 
of the next line whenever a <LF> is displayed. This code is set via the mode control 
sequences discussed under ‘Control Sequences for Screen Output.” 
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CONSOLE KEYBOARD INPUT 


If you read from the console device, the keyboard inputs are preprocessed for you and you will 
get ASCII characters, such as “B.” Most normal text-gathering programs will read from the con- 
sole device in this manner. Special programs, such as word processors and music keyboard pro- 
grams, will use raw input. Keys are converted via the keymap associated with the unit. 


The sections below deal with the following topics: 
o Setting up for console I/O (creating an I/O request structure) 
o Writing to the console to control its behavior 
o Reading from the console 


o Closing down a console device 


Creating an I/O Request 


This section shows you how to set up for console I/O. Console I/O, like that used with other 
devices, requires that you create an I/O request message that you pass to the console device for 
processing. The message contains the command as well as a data area. In the data area, for a 
write, there will be a pointer to the stream of information you wish to write to the console. For 
a read, this data pointer shows where the console is to copy the data it has for you. There is 


also a length field that says how many characters (maximum) are to be copied either from or to 
the console device. 


Here is a program fragment that can be used to create the message block that you use for con- 
sole communications. 


For writing to the console: 


struct IOStdReq *consoleWriteMsg; /* I/O request block pointer */ 
struct Port *consoleWritePort; /* a port at which to receive replies* / 


consoleWritePort = CreatePort(” mycon.write’” ,O); 


if(consoleWritePort == 0) exit(100);  =//* error in createport */ 
consoleWriteMsg = CreateStdIO(consoleWriteP ort); 
if(consoleWriteMsg —= 0) exit(200); = /* error in createstdio */ 
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For reading from the console: 


struct IOStdReq *consoleReadMsg; /* I/O request block pointer */ 
struct Port *consoleReadPort; /* a port at which to receive replies */ 


consoleReadPort = CreatePort(” mycon.read” ,O); 


if(consoleReadPort == 0) exit(300); | _/* error in createport */ 
consoleReadMsg — CreateStdIO(consoleReadPort); 
if(consoleReadMsg == 0) exit(400); /* error in createstdio */ 


These fragments show two messages and ports being set up. You would use this set-up if you 
want to have a read command continuously queued up while using a separate message with its 
associated port to send control command sequences to the console. In addition, if you want to 
queue up multiple commands to the console, you may wish to create multiple messages (but 
probably just one port for receiving replied messages from the device). 


Opening a Console Device 


For other devices, you normally use OpenDevice() to pass an uninitialized IORequest block 
to the device. For a console device, a slightly different method is used. You must have initial- 
ized two fields in the request block; namely, the data pointer and the length field. Here is a 
subroutine that can be used to open a console device (attach it to an existing window). It 
assumes that intuition.library is already open, a window has also been opened, and this new 
console is to be attached to the open window. 
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/* this function returns a value of 0 if the console 
* device opened correctly and a nonzero value 
* (the error returned from OpenDevice) if there was an error. 


*/ 


OpenConsole(writerequest,readrequest,window) 

struct IOStdReq *writerequest; 

struct [OStdReq *readrequest; 

struct Window *window; 

{ 
int error; 
writerequest->io_Data = (APTR) window; 
writerequest- >io_Length = sizeof(*window); 
error = OpenDevice(”console.device”, 0, writerequest, 0); 
readrequest- >io_Device = writerequest- > io_Device; 
readrequest->io_Unit = writerequest->io_Unit; 

/* clone required parts of the request * / 

return(error); 


} 


Notice that this routine opens the console using one I/O request (write), then copies the write 


request values into the read request. This assures that both input and output go to the same 
console device. 


SENDING A CHARACTER STREAM TO THE CONSOLE DEVICE 


To perform console I/O, you fill in fields of the console I/O standard request and pass this block 
to the console device using one of the normal I/O functions. When the console device has com- 
pleted the action, the device returns the message block to the port you have designated within 
the message itself. The function CreateStdIO() initializes the message to contain the address 
of the ReplyPort. 


The following subroutines use the IOStdReq created above. Note that the [OStdReq itself 
contains a pointer to the unit with which it is communicating. Thus, a single function can be 
used to communicate with multiple consoles. 
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/* output a single character to a specified console * / 


ConPutChar(request,character) 

struct [OStdReq *request; 

char character; 

{ 
request- >io_Command = CMD_WRITE; 
request- >io_Data = &character; 
request- >io_Length = 1; 
DolO(request); 
return; 


} 


/* output a stream of known length to a console */ 


ConWrite(request,string,length) 

struct [OStdReq *request; 

char *string; 

int length; 

{ 
request- >io_Command = CMD_WRITE; 
request- >io_Data = string; 
request->io_Length = length; 
DolO(request); 
return; 


} 
/* output a NULL-terminated string of characters to a console */ 


ConPutStr(request,string) 

struct [OStdReq *request; 

char *string; 

{ 

request- >io_ Command = CMD_WRITE; 

request- >io_Data = string; 

request->io_Length = -1; /* tells console to end when it sees a 


* terminating zero on the string. */ 
DoIO(request); 
return; 
j 
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Control Sequences for Screen Output 


Table 8-1 lists the functions that the console device supports, along with the character stream 
that you must send to the console to produce the effect. Where the function table indicates 
multiple characters, it is more efficient to use the ConWrite() function rather than 
ConPutChar() because it avoids the overhead of transferring the message block multiple 
times. The table below uses the second form of <CSI>, that is, the hex value 9B, to minimize 
the number of characters to be transmitted to produce a function. 


In table 8-1, if an item is enclosed in square brackets, it is optional and may be omitted. For 
example, for INSERT |N] CHARACTERS the value for N or M is shown as optional. The con- 
sole device responds to such optional items by treating the value of N as if it is not specified. 


The value of N or M is always a decimal number, having one or more ASCII digits to express its 
value. 


Table 8-1: Console Control Sequences 


Command Sequence of Characters 


(in Hexadecimal Form) 


BACKSPACE (move left one column) 08 
LINE FEED (move down one text line as OA 
specified by the mode function below) 
VERTICAL TAB (move up one text line) OB 
FORM FEED (clear the console’s screen) OC 
CARRIAGE RETURN (move to first column) OD 
SHIFT IN (undo SHIFT OUT) OE 
SHIFT OUT (set MSB of each character OF 


before displaying) 


ESC (escape; can be part of the control 1B 
sequence introducer) 
CSI (control sequence introducer) 


RESET TO INITIAL STATE 1B 63 
INSERT [N] CHARACTERS 9B [N] 40 


(Inserts one or more spaces, shifting the 
remainder of the line to the right.) 


CURSOR UP [N| CHARACTER POSITIONS — 9B [N| 41 
(default = 1) 

CURSOR DOWN |N] CHARACTER 9B |N] 42 
POSITIONS 
(default = 1) 
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CURSOR FORWARD [N] CHARACTER 9B |N] 43 
POSITIONS (default = 1) 


CURSOR BACKWARD |[N] CHARACTER 9B [N] 44 
POSITIONS (default = 1) 
CURSOR NEXT LINE |[N] (to column 1) 9B [N] 45 
CURSOR PRECEDING LINE [N| 9B |N] 46 
(to column 1) 
MOVE CURSOR TO ROW; COLUMN 9B [N] [3B N] 48 


where N is row, M is column, and 
semicolon (hex 3B) must be present 

as a separator, or if row is left 

out, so the console device can tell 

that the number after the semicolon 
actually represents the column number. 


ERASE TO END OF DISPLAY 9B 4A 

ERASE TO END OF LINE 9B 4B 

INSERT LINE (above the line containing 9B 4C 
the cursor) 

DELETE LINE (remove current line, move 9B 4D 


all lines up one position to fill 
gap, blank bottom line) 

DELETE CHARACTER |N] (that cursor is 9B [N] 50 
sitting on and to the right if 
[N] is specified) 

SCROLL UP [N] LINES (Remove line(s) from = 9B [N] 53 
top of screen, move all other lines 
up, blanks [N] bottom lines) 

SCROLL DOWN |[N] LINES (Remove line(s) 9B [N] 54 
from bottom of screen, move all 
other lines down, blanks [N] top lines) 

SET MODE (cause LINEFEED to respond as 9B 32 30 68 
RETURN-LINEFEED) 

RESET MODE (cause LINEFEED to respond 9B 32 30 6C 
only as LINEFEED) 

DEVICE STATUS REPORT (cause console to 9B 36 6E 
insert into your read-stream a CURSOR 
POSITION REPORT; see ‘“‘Reading from 
the Console’’ for more information) 

SELECT GRAPHIC RENDITION See note below. 
<style>;<fg>;<bg>6D 
(select text style foreground 
color, background color) 
(See the note below.) 
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Note: For SELECT GRAPHIC RENDITION, any number of parameters, in any order, are 


valid. They are separated by semicolons. The parameters follow: 


<style> = 

0 Plain text 

1 Bold-face 

3 Italic 

4 Underscore 

7 Inverse-video 
aie == 

30 - 37 Selecting system colors 0-7 for foreground. 

Transmitted as two ASCII characters. 

<bg> = 

40 - 47 selecting system colors 0-7 for background. 


Transmitted as two ASCII characters. 


For example, to select bold face, with color 3 as foreground and color 0 as back- 
ground, send the sequence: 


9B 31 3B 33 33 3B 34 30 6D 


representing the ASCII sequence: 


” < CSI>1;33;40m” 


where <CSI> is the control sequence introducer, here used as the single-character 


value 9B hex. 


The sequences in table 8-2 are not ANSI standard sequences; they are private Amiga 


sequences. 


In these command descriptions, length, width, and offset are comprised of one or more 
ASCII digits, defining a decimal value. 
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Table 8-2: Amiga Console-control Sequences 


Command Sequence of Characters 
(in Hexadecimal Form) 


SET PAGE LENGTH (in character raster lines, 
causes console to recalculate, 
using current font, how many text 9B <length> 74 
lines will fit on the page. 


SET LINE LENGTH (in character positions, 
using current font, how many characters 
should be placed on each line). 9B <width> 75 


SET LEFT OFFSET (in raster columns, how far 
from the left of the window 
should the text begin). 9B <offset> 78 


SET TOP OFFSET (in raster lines, how far 
from the top of the window’s 
RastPort should the topmost 
line of the character begin). 9B <offset> 79 


SET RAW EVENTS — see the separate 
topic “Selecting Raw Input Events’’ 
below for more details. 


RESET RAW EVENTS — see 


‘Selecting Raw Input Events” below. 
SET CURSOR RENDITION - make the 


cursor visible or invisible: 


Invisible: 9B 30 20 70 
Visible: 9B 20 70 


WINDOW STATUS REQUEST - ask the 
console device to tell you the 
current bounds of the window, 
in upper and lower row and 
column character positions. 
(User may have resized or 


repositioned it.) See 
‘“Window Bounds Report”’ below. 9B 30 20 71 


Note: The console device normally handles the SET PAGE LENGTH, SET LINE 
LENGTH, SET LEFT OFFSET, and SET TOP OFFSET functions automatically. 
To allow it to do so again after setting your own values, you can send the function 
without a parameter. 


284 Console Device 


Examples 


Move cursor right by lL: 


Character string equivalents: <CSI>C or <CSI>1C 
Numeric (hex) equivalents: 9B 43 9B 31 43 


Move cursor right by 20: 


Character string equivalent: <CSI>20C 
Numeric (hex) equivalent: 9B 32 30 43 


Move cursor to upper left corner (home): 


Character string equivalents: 
<CSI>H or 
<CSI>1;1H or 
<CSI>;1H or 
<CSI>1;H 


Numeric (hex) equivalents: 
9B 48 
9B 31 3B 31 48 
9B 3B 31 48 
9B 31 3B 48 


Move cursor to the fourth column of the first line of the window: 


Character string equivalents: 
<CSI>1;4H or 
<CSI>;4H 


Numeric (hex) equivalents: 
9B 31 3B 34 48 
9B 3B 34 48 
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Clear the screen: 


Character string equivalents: 
<FF> or CTRL-L {clear screen character} or 
<CSI>H<CSI>J {home and clear to end of screen} or 


Numeric (hex) equivalents: 
OC 
9B 48 9B 4A 


READING FROM THE CONSOLE 


Reading input from the console device returns an ANSI 3.64 standard byte stream. This stream 
may contain normal characters and/or RAW input event information. You may also request 
other RAW input events using the SET RAW EVENTS and RESET RAW EVENTS control 


sequences discussed below. See ‘“‘Selection of Raw Input Events.’’ 


The following subroutines are useful for setting up for console reads. Only a single-character- 
at-a-time version is shown here. 


Note: This example does not illustrate the fact that a request for more than one character can 
be satisfied by only one, thus requiring you to look at io_Actual. 


/* queue up a read request to a console, show where to put the character when ready 
* to be returned. Most efficient if this is called right after console is opened */ 


QueueRead(request, whereto) 

struct IOStdReq *request; 

char *whereto; 

{ 
request- >1io_Command = CMD_READ; 
request- >10_Data = whereto; 
request- >10_Length = 1; 
SendIO(request); 


return; 


} 


/* see if there is a character to read. If none, don’t wait, 
* come back with a value of -1 */ 

int 

ConMayGetChar(consolePort,request, whereto) 

struct Port *consolePort; 
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struct IOStdReq *request; 
char *whereto; 


{ 


register temp; 


if ( GetMsg(consolePort) === NULL ) return(-1); 
temp = *whereto; 

QueueRead(request,whereto); 

return(temp); 


} 


/* go and get a character; put the task to sleep if 
* there isn’t one present */ 


UBYTE 
ConGetChar(consolePort,request,whereto) 
struct [OStdReq *request; 
struct Port *consolePort; 
char *whereto; 
{ 
register temp; 
while((GetMsg(consolePort) === NULL)) WaitPort(consolePort); 


temp = *whereto;  /* get the character */ 
QueueRead(request,whereto); 
return(temp); 


INFORMATION ABOUT THE READ-STREAM 


For the most part, keys whose keycaps are labeled with ANSI standard characters will ordi- 
narily be translated into their ASCII-equivalent character by the console device through the use 
of its keymap. A separate section in this chapter has been dedicated to the method used to 
establish a keymap and the internal organization of the keymap. 


For keys other than those with normal ASCII equivalents, an escape sequence is generated and 
inserted into your input stream. For example, in the default state (no raw input events 
selected) the function and arrow keys will cause the sequences shown in table 8-3 to be inserted 
in the input stream. 
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Table 8-3: Special Key Report Sequences 


Key Unshifted Sends Shifted Sends 

F1 <CSI>0° <CSI>107 

F2 <CSI>1° <CSI>11° 

F3 <CSI>2° <CSI>12° 

F4 <CSI>3° <CSI>13° 

F5 <CSI>4° <CSI>14° 

F6 <CSI>5— <CSI>15" 

F7 <CSI>6° <CSI>16™ 

F8 <CSI>7~ <CSI>17— 

F9 <CSI>8" <CSI>18" 

F10 <CSI>9° <CSI>19° 

HELP <CSI>?" <CSI>?" (same) 

Arrow keys: 

Up <CSI>A <CSI>T 

Down <CSI>B <CSI>$ 

Left <CSI>D <CSI> A (notice the space 
Right <CSI>C <CSI> @ after <CSI>) 


CURSOR POSITION REPORT 


If you have sent the DEVICE STATUS REPORT command sequence, the console device 


returns a cursor position report into your input stream. It takes the form: 


<CSI><row>;<column>R 


For example, if the cursor is at column 40 and row 12, here are the ASCII values you receive in 
a stream: 


9B 34 30 3B 31 32 52 
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WINDOW BOUNDS REPORT 


A user may have either moved or resized the window to which your console is bound. By issu- 
ing a WINDOW STATUS REPORT to the console, you can read the current position and size 
in the input stream. This window bounds report takes the following form: 


<CSI>1;1;<bottom margin>;<right margin>r 


Note that the top and left margins are always 11 for the Amiga. The bottom and right margins 
give you the window row and column dimensions as well. For a window that holds 20 lines 
with 60 characters per line, you will receive the following in the input stream: 


9B 31 3B 31 3B 32 30 3B 36 30 20 72 


SELECTING RAW INPUT EVENTS 


If the keyboard information — including ‘‘cooked”’ keystrokes— does not give you enough infor- 
mation about input events, you can request additional information from the console driver. 


The command to SET RAW EVENTS is formatted as: 


” <CSI> |event-types-separated-by-semicolons]{” 


If, for example, you need to know when each key is pressed and released you would request 
“RAW keyboard input.” This is done by writing ‘““<CSI>1{” to the console. In a single SET 
RAW EVENTS request, you can ask the console to set up for multiple event types at one time. 
You must send multiple numeric parameters, separating them by semicolons (;). For example, 
to ask for gadget pressed, gadget released, and close gadget events, write “<CSI>7;8;11{” (all 
as ASCII characters, without the quotes). 


You can reset, that is, delete from reporting, one or more of the raw input event types by using 
the RESET RAW EVENTS command, in the same manner as the SET RAW EVENTS was 


used to establish them in the first place. This command stream is formatted as: 


<CSI> [event-types-separated-by-semicolons]} 


So, for example, you could reset all of the events set in the above example by transmitting the 
command sequence: ‘“<CSI>7;8;11}.” Table 8-4 is a list of the valid raw input event types. 
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Table 8-4: Raw Input Event Types 


Request 
Number Description 


No-op Used internally 

1 RAW keyboard input Intuition swallows all except 
the select button 

2 RAW mouse input 

3 Event Sent whenever your 
window is made active 

4 Pointer position 

5 (unused) 

6 Timer 

7 Gadget pressed 

8 Gadget released 

9 Requester activity 

10 Menu numbers 

11 Close Gadget 

12 Window resized 

13 Window refreshed 

14 Preferences changed 

15 Disk removed 

16 Disk inserted 


Complex Input Event Reports 


If you select any of these events you will start to get information about the events in the follow- 
ing form: 


<CSI> <class>;<subclass>;<keycode>;<qualifiers>;<x>;<y>; 
<seconds>;< microseconds > | 


where 


<CSI> 


is a one-byte field. It is the ‘“‘control sequence introducer’’, 9B in hex. 


<class > 
is the RAW input event type, from the above table. 
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<subclass > 


is usually 0. If the mouse is moved to the right controller, this would be 1. 


<keycode> 


indicates which key number was pressed (see figure 8-1 and table 8-6). This field can also 
be used for mouse information. 


< qualifiers > 


indicates the state of the keyboard and system. The qualifiers are defined as shown in table 


8-5. 


Bit 


Noe © 


12 
13 
14 
lo 


Mask 


0001 
0002 
0004 


0008 
0010 
0020 
0040 
0080 
0100 
0200 
0400 
0800 


1000 
2000 
4000 
8000 


Table 8-5: Input Event Qualifiers 


Key 


Left shift 

Right shift 

Caps Lock Associated keycode is 
special; see below. 


Ctrl 

Left Alt 

Right Alt 

Left Amiga key pressed 
Right Amiga key pressed 
Numeric pad 


Repeat 
Interrupt Not currently used. 
Multi-broadcast This window (active one) 


or all windows. 
Left mouse button 
Right mouse button 
Middle mouse button (Not available on standard mouse) 
Relative mouse Indicates mouse coordinates 
are relative, not absolute. 


The Caps Lock key is handled in a special manner. It generates a keycode only when it is 
pressed, not when it is released. However, the up/down bit (80 hex) is still used and reported. 
If pressing the Caps Lock key causes the LED to light, keycode 62 (Caps Lock pressed) is sent. 
If pressing the Caps Lock key extinguishes the LED, keycode 190 (Caps Lock released) is sent. 
In effect, the keyboard reports this key as held down until it is struck again. 


The <x> and <y> fields are filled by some classes with an Intuition address: x << 16+. 
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The <seconds> and <microseconds> fields contain the system time stamp taken at the time 
the event occurred. These values are stored as long-words by the system. 


With RAW keyboard input selected, keys will no longer return a simple one-character “‘A”’ to 
“7 but will instead return raw keycode reports of the form: 


<CSI>1;0;<keycode>;< qualifiers > ;0;0;<seconds>;< microseconds > | 


For example, if the user pressed and released the “‘B” key with the left Shift and right Amiga 
keys also pressed, you might receive the following data: 


<CSI> 1;0;35;129;0;0;23987;99| 
<CSI> 1;0;163;129;0;0;24003;18| 


The <keycode> field is an ASCII decimal value representing the key pressed or released. 
Adding 128 to the pressed key code will result in the released keycode. Figure 4-1 lets you con- 
vert quickly from a key to its keycode. The tables let you convert quickly from a keycode to a 
key. 


F7 F8 F9 DEL 
56 |'s7 |'ss | 60 [a6 
; A i 7 8 9 
08 '02 om 08 Loc] oo 
U \ Oo P ' 4 5 6 
16/17 [a | ro [vale 


CTRL aoe A ) D H J K L ‘ RETURN A 
SHIFT Zz Xx Cc B N M < > ? SHIFT + > 
a1 | 3 2 jor _|ac 
Al ALT v = ENTER 
wr Fs 





Figure 8-1: The Amiga Keyboard, Showing Keycodes in Hex 


The default values given correspond to the values the console device will return when these keys 
are pressed and the keycaps as shipped with the standard American keyboard. 
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Table 8-6: System Default Console Key Mapping 


Raw Unshifted Shifted 

Key Keycap Default Default 
Number Legend Value Value 

00 = ‘(Accent grave) ~ (tilde) 

01 1! 1 ! 

02 2@ 2 @ 

03 3 #: 3 a 

04 4 $ 4 $ 

05 5 % 5 % 

06 6 * 6 7 

07 7 & i & 

08 8 * 8 * 

09 9 ( 9 ( 

OA 0 ) 0 ) 

OB - - (Hyphen) _ (Underscore) 
OC = = af 

oD \I \ | 

OE (undefined) 

OF 0 0 0 (Numeric pad) 
10 Q q Q 

11 W Ww W 

12 E e E 

13 R r R 

14 T t T 

15 Y y Y 

16 U u U 

17 | i I 

18 O O O 

19 r p P 

1A 4 | { 

1B ls | } 

1C (undefined) 

1D 1 1 1 (Numeric pad) 
1E 2 2 2 (Numeric pad) 
1F 3 3 3 (Numeric pad) 
20 A a A 

21 S S S 

22 D d D 

23 F f F 

24 G g G 
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Raw 
Key Keycap 
Number Legend 


29 H 
26 J 
27 K 
28 L 
29 
2A es 
2B 

2C 

2D 4 
2E 
2F 


oO ON 


30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
3A 
3B 
3C . 
3D 7 
3K 8 
3F 9 


ZZ2w<axXn 


Saad 


sae 


40 (Space bar) 
41 Back Space 
42 Tab 

43 Enter 

44 Return 

45 Esc 

46 Del 

47 

48 

49 

4A 

4B 
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Unshifted 
Default 
Value 


h 
J 
k 


single quote) 
RESERVED) 
undefined) 


a ww Ne 


moo 


(RESERVED) 


Z 
Xx 
c 
Vv 
b 
n 
m 


, (comma) 
. (period) 


/ 
(undefined) 


7 
8 
9 


20 
O8 
O9 
OD 
OD 
1B 
7F 
(undefined) 
(undefined) 
(undefined) 
( 


undefined ) 


Shifted 
Default 
Value 


93 


(RESERVED) 

4 (Numeric pad) 
5 (Numeric pad) 
6 (Numeric pad) 


(RESERVED) 


Z 
xX 
C 
V 
B 
N 
M 
<< 
= 


oo) 


. (Numeric pad) 
7 (Numeric pad) 
8 (Numeric pad) 
9 (Numeric pad) 


20 
O8 
O9 
OD (Numeric pad) 
OD 
1B 
7F 


- (Numeric Pad) 


Raw 
Key 
Number 


4C 
4D 
4 


4 


50 
ol 
o2 
o3 
54 
55 
56 
57 
o8 
o9 
5A 
5B 
5C 
5D 
5E 
SF 


Keycap 
Legend 


Up arrow 

Down arrow 
Forward arrow 
(note blank space 
after <CSI>) 
Backward arrow 
(note blank space 
after <CSI>) 


Fl 
F2 
F3 
F4 
F5 
F6 
F7 
F8 
F9 
F10 


HELP 


Unshifted 
Default 
Value 


<CSI>A 
<CSI>B 
<CSI>C 


<CSI>D 


<CSI>0° 
<CSI>1° 
<CSI>2° 
<CSI>37 
<CSI>4° 
<CSI>57 
<CSI>67 
<CSI>7~ 
<CSI>8" 
<CSI>9° 
(undefined) 
(undefined) 
(undefined) 
(undefined) 
(undefined) 
<CSI>?" 


Shifted 
Default 
Value 


<CSI>T 
<CSI>S 
<CSI> A 


<CSI> @ 


<CSI>10°™ 
<CSI>11° 
<CSI>12° 
<CSI>13° 
<CSI>14" 
<CSI>15" 
<CSI> 16" 
<CSI>177 
<CSI>18" 
<CSI>19° 


<CSI>?" 
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Raw 
Key 


Number 
60 
61 
62 


63 


64 
65 


66 
67 


68 


69 


6A 


6B 
6C 
6D 
6E 
6F 
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Function or 
Keycap 
Legend 


Shift (left of space bar) 
Shift (right of space bar) 
Caps Lock 

Ctrl 


(Left) Alt 
(Right) Alt 


Amiga (left of space bar) 
Amiga (right of space bar) 


Left mouse button 
(not converted) 

Right mouse button 
(not converted) 


Middle mouse button 
(not converted) 


(undefined) 
(undefined) 
(undefined) 
(undefined) 
(undefined) 


Close Amiga 
Open Amiga 


Inputs are only for the 
mouse connected to Intuition, 
currently “gameport”’ one. 


Raw Key Number 


70-7F 
80-F'8 


F9 


FA 
FB 


FC 


FD 


FE 
FF 
FF 


Notes about the preceding table: 


1) “(undefined)” indicates that the current keyboard design should not generate this 
number. If you are using SetKeyMap() to change the key map, the entries for these 
numbers must still be included. 


2) ‘(not converted)” refers to mouse button events. 
“<CSI>2{” to inform the console driver that you wish to receive mouse events; other- 


Function 


(undefined) 


Up transition (release or unpress key of one 
of the above keys) (80 for 00, F8 for 7F) 


Last keycode was bad 
(was sent in order to resynchronize) 


Keyboard buffer overflow 


(undefined, reserved for 
keyboard processor catastrophe) 


Keyboard selftest failed 


Power-up key stream start. 
Keys pressed or stuck at power-up 
will be sent between FD and FE. 


Power-up key stream end 
(undefined, reserved) 


Mouse event, movement only, 
no button change (not converted) 


wise these will not be transmitted. 


3) “(RESERVED)” indicates that these keycodes have been reserved for non-US key- 
boards. The ‘‘2B” code key will be between the double-quote(”) and Return keys. The 


‘*30”’ code key will be between the Shift and ‘‘Z” keys. 


Keymapping 


The Amiga has the capability of mapping the keyboard in any manner that you wish. In other 
computers, this capability is normally provided through the use of “keyboard enhancers.”’ In the 
Amiga, however, the capability is already present and the vectors that control the remapping 


are user-accessible. 
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You must use the sequence 


The functions called AskKeyMap() and SetKeyMap() each deal with a set of eight longword 
pointers, known as the KeyMap data structure. The KeyMap data structure is shown below. 


struct KeyMap { 

UBYTE *km_LoKeyMapTypes; 
ULONG *km_LoKeyMap; 
UBYTE *km_LoCapsable; 
UBYTE *km_LoRepeatable; 
UBYTE *km_HikeyMapTypes; 
ULONG *km_Hikey Map; 
UBYTE *km_HiCapsable; 
UBYTE *km_HiRepeatable; 


3 


The function AskKeyMap() shown below does not return a pointer to a table of pointers to 
currently assigned key mapping. Instead, it copies the current set of pointers to a user- 
designated area of memory. AskKeyMap() returns a TRUE/FALSE value that says whether 
or not the function succeeded. 


The function SetKeyMap(), also shown below, copies the designated key map data structure 
to the console device. Thus this routine is complementary to AskKeymap() in that it can 
restore an original key mapping as well as establish a new one. 


/* this include file is needed as well as 
* other normal console includes * / 


#include ” devices/keymap.h” 


int AskKeyMap(request,keymap) 
struct [OStdReq *request; 
struct KeyMap *keymap; 


int i; 

request- >io_Command = CD_ASKKEYMAP; 
request- >io_Length = sizeof(struct KeyMap); 
request- >io_Data = keymap;/* where to put it */ 
DolO(request); 

i = request- >io_Error; 

if(i) return(FALSE); 

else return(TRUE);/* if no error, it worked. */ 
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int SetKeyMap(request,keymap) 
struct [OStdReq *request; 
struct KeyMap *keymap; 


int 1; 

request- >io_Command = CD_SETKEYMAP; 
request->io_Length = sizeof(struct KeyMap); 
request- >io_Data = keymap; /* where to get it */ 
DoIO(request); 

i = request->io_Error; 

if(i) return(FALSE); 

else return(TRUE);  /* if no error, it worked. */ 


} 


As a prelude to the following material, note that the Amiga keyboard transmits raw key infor- 
mation to the computer in the form of a key position and a transition. Figure 8-1 shows a phy- 
sical layout of the keys and the hexadecimal number that is transmitted to the system when a 
key is pressed. When the key is released, its value, plus hexadecimal 80, is transmitted to the 
computer. The key mapping described herein refers to the translation from this raw key 
transmission into console device output to the user. 


The low key map provides translation of the key values from hex 00-3F; the high key map pro- 
vides translation of key values from hex 40-67. Raw output from the keyboard for the low key 


map does not include the space bar, Tab, Alt, Ctrl, arrow keys, and several other keys (see 
figure 8-2 and table 8-7). 


00 01 02 03 04 O05 06 O07 O08 09 OA OB OC OD 3D 3E 35 


10 11 12 #13 14 #15 16 17 #18 #19 1A 4I1B 2D 2E 2F 
20 21 22 23 24 25 26 27 28 29 2A 1D 1E IF 
31 32 33 34 35 36 37 38 39 3A OF 3C 
~~ 1! 2@ 34 48 5% 67 7& 8* 9( O) -_L =+ \ 7 8 9 
qQ wW eE rR tT yY uJ iI o0 pP [{ J} 4 5 6 
ak sS @D fF gG hH jJ kK 1L ;: ' 1 2 3 
zZ xX cC vV bB nN mM ,< .> /? 0 


Figure 8-2: Low Key Map Translation Table 
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Table 8-7: High Key Map Hex Values 


Key Number 


40 
41 
42 
43 
44 
45 
46 
4A 
AC 
4D 
4E 
4F 
50-59 
5F 
60 
61 
62 
63 
64 
65 
66 
67 


The keymap table for the low and high keymaps consists of 4-byte entries, one per hex keycode. 


Function or 
Keycap Legend 


Space 

Backspace 

Tab 

Enter 

Return 

Escape 

Delete 

Numeric Pad - character 
Cursor Up 
Cursor Down 
Cursor Forward 
Cursor Backward 
Function keys F1-F10 
Help 

Left Shift 

Right Shift 

Caps Lock 
Control 

Left Alt 

Right Alt 

Left Amiga 
Right Amiga 


These entries are interpreted in one of two possible ways: 


o As four separate bytes, specifying how the key is to be interpreted when pressed alone, 
with one qualifier, with another qualifier, or with both qualifiers (where a qualifier is one 


of three possible keys: Ctrl, Alt, or Shift). 


o As alongword containing the address of a string descriptor, where a string of hex digits 
is to be output when this key is pressed. If a string is to be output, any combination of 


qualifiers may affect the string that may be transmitted. 


Note: The keymap table must begin aligned on a word boundary. Each entry is four bytes 
long, thereby maintaining word alignment throughout the table. This is necessary because some 
of the entries may be longword addresses and must be aligned properly for the 68000. 
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ABOUT QUALIFIERS 


As you may have noticed, there are three possible qualifiers, but only a 4-byte space in the table 
for each key. This does not allow space to describe what the computer should output for all 
possible combinations of qualifiers. This problem is solved by only allowing all three qualifiers 
to affect the output at the same time in string mode. Here is how that works. 


For ‘‘vanilla’”’ keys, such as the alphabetic keys, use the 4 bytes to represent the data output for 
the key alone, Shifted key, Alt’ed key, and Shifted-and-Alt’ed key. Then for the Ctrl-key-plus- 
vanilla-key, use the code for the key alone with bits 6 and 5 set to 0. 


For other keys, such as the Return key or Esc key, the qualifiers specified in the keytypes table 
(up to two) are the qualifiers used to establish the response to the key. This is done as follows. 
In the keytypes table, the values listed for the key types are those listed for the qualifiers in 
devices/keymap.h and devices/keymap.t. Specifically, these qualifier equates are: 


KC_NOQUAL 0x00 
KCF_SHIFT 0x01 
KCF_ALT Ox02 


KCF_CONTROL — 0x04 
KC_VANILLA 0x07 
KCF_DOWNUP 0x08 
KCF_STRING 0x40 


As shown above, the qualifiers for the various types of keys occupy specific bit positions in the 
key types control byte. 


In assembly code, a keymap table entry looks like this: 


SOME_KEY: 
DC.B VALUE_1, VALUE_2, VALUE_3, VALUE_4 


Table 8-8 shows how to interpret the keymap for various combinations of the qualifier bits. 
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Table 8-8: Keymap Qualifier Bits 


If Keytype is: Then value in this position in the 
keytable is output when the key is 
pressed along with: 


KC_NOQUAL - - - alone 
KCF_SHIFT - - Shift alone 
KCF_ALT - - Alt alone 
KCF_CONTROL - - Ctrl alone 
KCF_ALT+KCF_SHIFT Shift+Alt Alt Shift alone 


KCF_CONTROL+KCF_ALT Ctrl+Alt Ctrl Alt alone 
KCF_CONTROL+KCF_SHIFT  Ctrl+Shift Ctrl Shift alone 
KC_VANILLA Shift+Alt Alt Shift alonex 


* Special case— Ctrl key, when pressed with one of the alphabet keys and certain others, 
is to output key-alone value with the bits 6 and 5 set to zero. 


KEYTYPE TABLE ENTRIES 


The vectors named km_LoKeyTypes and km_HikKeyTypes contain one byte per raw key code. 
This byte defines the entry type that is made in the key table by a set of bit positions. 


Possible key types are: 
o Any of the qualifier groupings noted above 


o KCF_STRING + any combination of KCF_SHIFT, KCF_ALT, KCF_CONTROL (or 
KC_NOQUAL) if the result of pressing the key is to be a stream of bytes (and key- 
with-one-or-more-qualifiers is to be one or more alternate streams of bytes). 


Any key can be made to output up to eight unique byte streams if KCF_STRING 1s set 
in its keytype. The only limitation is that the total length of all of the strings assigned 
to a key be within the “jump range” of a single byte increment. See the “‘String- 
Output Keys” section below for more information. 


The low keytype table covers the raw keycodes from hex 00-3F and contains one byte per key- 
code. Therefore this table contains 64 (decimal) bytes. The high keytype table covers the raw 
keycodes from hex 40-67 and contains 38 (decimal) bytes. 
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STRING-OUTPUT KEYS 


When a key is to output a string, the keymap table contains the address of a string descriptor 
in place of a 4-byte mapping of a key as shown above. Here is a partial table for a new high 
key map table that contains only three entries thus far. The first two are for the space bar and 
the backspace key; the third is for the tab key, which is to output a string that says “‘/TAB).” 
An alternate string, ‘““[SHIFTED-TAB],” is also to be output when a shifted TAB key is pressed. 


newHiMapTypes: 


DC.B 
DC.B 


newHiMap: 


DC.B 
DC.B 
DC.L 


newkey42: 
DC.B 


DC.B 


DC.B 


DC.B 


new42us: 


DC.B 
new42ue: 


new 42ss: 


DC.B 


new 42se: 


KCF_ALT,KC_NOQUAL, 
KCF_STRING+KCF_SHIFT, 


0,0,$A0,$20 
0,0,0,$08 
newkey42 


new42ue - new42us 


new42us - newkey42 


new42se - new42ss 


new42ss - newkey42 


*(TAB)’ 


*>(SHIF TED-TAB]’ 


;(more) 


sspace bar, and Alt-space bar 
;Back Space key only 

snew definition for string to 
soutput for Tab key 

;(more) 


slength of the 
sunshifted string 


snumber of bytes from start of 
;string descriptor to start of 
sthis string 


slength of the shifted string 
snumber of bytes from start of 


sstring descriptor to start of 
sthis string 


The new high map table points to the string descriptor at address newkey42. The new high 
map types table says that there is one qualifier, which means that there are two strings in the 
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key string descriptor. 


Each string in the descriptor takes two bytes in this part of the table: the first byte is the 
length of the string, and the second byte is the distance from the start of the descriptor to the 
start of the string. Therefore, a single string (KCF_STRING + KC_NOQUAL) takes 2 bytes of 
string descriptor. If there is one qualifier, 4 bytes of descriptor are used. If there are two 
qualifiers, 8 bytes of descriptor are used. If there are 3 qualifiers, 16 bytes of descriptor are 
used. All strings start immediately following the string descriptor in that they are accessed as 
single-byte offsets from the start of the descriptor itself. Therefore, the distance from the start 
of the descriptor to the last string in the set (the one that uses the entire set of specified 
qualifiers) must start within 255 bytes of the descriptor address. 


Because the length of the string is contained in a single byte, the length of any single string 
must be 255 bytes or less while also meeting the ‘‘reach’’ requirement. However, the console 
input buffer size limits the string output from any individual key to 32 bytes maximum. 


The length of a keymap containing string descriptors and strings is variable and depends on the 
number and size of the strings that you provide. 


CAPSABLE BIT TABLE 


The vectors called km_LoCapsable and km_HiCapsable point to the first byte in an 8-byte table 
that contains more information about the keytable entries. Specifically, if the Caps Lock key 
has been pressed (the Caps Lock LED is on) and if there is a bit on in that position in the caps- 
able map, then this key will be treated as though the Shift key is now currently pressed. For 
example, in the default key mapping, the alphabetic keys are “‘capsable” but the punctuation 
keys are not. This allows you to set the Caps Lock key, just as on a normal typewriter, and get 
all capital letters. However, unlike a normal typewriter, you need not go out of Caps Lock to 
correctly type the punctuation symbols or numeric keys. 


In the table, the bits that control this feature are numbered from the lowest bit in the byte, and 
from the lowest memory byte address to the highest. For example, the bit representing capsable 
status for the key that transmits raw code 00 is bit O in byte 0; for the key that transmits raw 
code 08 it is bit 0 in byte 1, and so on. 


There are 64 bits (8-bytes) in each of the two capsable tables. 
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REPEATABLE BIT TABLE 


For both the low and high key maps there is an 8-byte table that provides one bit per possible 
raw key code. This bit indicates whether or not the specified key should repeat at the rate set 


by the Preferences program. The bit positions correspond to those specified in the capsable bit 
table. 


If there is a 1 in a specific position, the key can repeat. The vectors that point to these tables 
are called km_LoRepeatable and km_HiRepeatable. 


DEFAULT LOW KEY MAP 


In the default low key map, all of the keys are treated in the same manner: 
o When pressed alone, they transmit the ASCII equivalent of the unshifted key. 


o When Shifted, they translate the ASCII equivalent of the shifted value when printed on 
the keycap. 


o When “Alt’ed”’ (pressed along with an Alt key), they transmit the alone-value with the 
high bit of a byte set (value plus hex 80). 


o When Shifted and Alt’ed, they transmit the shifted-value plus hex 80. 


In this table, the bytes that describe the data to be transmitted are positioned as the example 
for the “A” key shown here: 


key_A DC.B_ (’A’)+380 _— ;Shifted and Alt’ed 
DC.B_ (’a’)+$80 _ ;Alt’ed only 
DC.B- (A’) sShifted only 
DC.B_ (’a’) snot Shifted or Alt’ed 


In addition to the response to the key alone, Shifted, Alt’ed, and Shifted-and-Alt’ed, the default 
low keymap also responds to the key combination of ‘“‘Ctrl + key” by stripping off bits 6 and 5 
of the generated data byte. For example, Ctrl + A generates the translated keycode 01 (61 with 
bits 6 and 5 set to 0). 


All keys in the low key map are mapped to their ASCII equivalents, as noted in the low key 
map key table shown above. 


Because the low key table contains 4 bytes per key, and describes the keys (raw codes) from hex 
00-3F, there are 64 times 4 or 256 bytes in this table. 
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DEFAULT HIGH KEY MAP 


Most of the keys in the high key map generate strings rather than single-character mapping. 
The following keys map characters with no qualifier, along with their byte mapping: 


Key 


BACKSP 
ENTER 
DEL 


Generates Value: 


$08 
$0D 
$7F 


The following keys map characters and use a single qualifier: 


Key 


SPACE 
RETURN 
ESC 


numeric pad “‘-”’ 


Generates Value: 


$20 
$0D 
$1B 


$2D 


The following keys generate strings: 
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If Used with Qualifier, 


Generates Value: 


$A0 (qualifier = ALT) 
$0A (qualifier = CONTROL) 
$9B (qualifier = ALT) 


$FF (qualifier = ALT) 


Key Generates Value: If Used with <SHIFT>, 


generates Value: 


TAB $09 $9B, followed by ’Z’ 
cursor: 

UP $9B, followed by ’A’ $9B, followed by ’T” 

DOWN $9B, followed by ’B’ $9B, followed by ’S’ 

FWD $9B, followed by ’C’ $9B, followed by ’ ’, 


followed by ’@’ 


BACKWD $9B, followed by ’D’ $9B, followed by ’ ’, 
followed by ’A’ 

function 

keys: 
Fl $9B, followed by ’0° ’ $9B, followed by 10° ’ 
F2 $9B, followed by ’17 ’ $9B, followed by 7117 ’ 
F3 $9B, followed by ’2° ’ $9B, followed by ’127 ’ 
F4 $9B, followed by ’37 ’ $9B, followed by 7137 ’ 
F5 $9B, followed by 4° ’ $9B, followed by 14° ’ 
F6 $9B, followed by ’5™ ’ $9B, followed by 7157 ’ 
F7 $9B, followed by ’6™ ’ $9B, followed by ’167 ’ 
F8 $9B, followed by ’77 ’ $9B, followed by 7177 ’ 
F9 $9B, followed by ’8” ’ $9B, followed by ’18° ’ 
F10 $9B, followed by 9° ’ $9B, followed by ’19° ’ 

HELP $9B, followed by ?” ’ (no qualifier used) 


Closing a Console Device 


When you have finished using a console, it must be closed so that the memory areas it utilized 
may be returned to the system memory manager. Here is a sequence that you can use to close a 
console device: 


CloseDevice(requestBlock); 


Note that you should also delete the messages and ports associated with this console after the 
console has been closed: 
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DeleteStdIO(consoleWriteMsg); 
DeleteStdIO(consoleRead Msg); 
DeletePort(consoleWritePort); 
DeletePort(consoleReadPort); 


If you have finished with the window used for the console device, you can now close it. 


Example Program 


The following is a console device demonstration program with supporting macro routines. 


/* cons.c */ 


/* This program is supported by the Amiga C compiler, version 1.1 and beyond. 
* (v1.0 compiler has difficulties if string variables do not have their initial 


* character aligned on a longword boundary. Compiles acceptably but won’t run 
* correctly.) 


* 


#include ”exec/types.h” 
#include ”exec/io.h” 
#include ”exec/memory.h” 


#include ” graphics/gfx.h” 
#include ”hardware/dmabits.h” 
#include ”hardware/custom.h” 
#include ”hardware/blit.h” 
#include ” graphics/gfxmacros.h” 
#include ” graphics/copper.h” 
#include ” graphics/view.h” 
#include ” graphics/gels.h” 
#include ” graphics /regions.h” 
#include ” graphics/clip.h” 
#include ” exec/exec.h” 
#include ” graphics /text.h” 
#include ” graphics/gfxbase.h” 


#include ” devices /console.h” 
#include ”devices/keymap.h” 


#include ” libraries/dos.h” 
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#include ” graphics /text.h” 
#include ” libraries/diskfont.h” 
#include ” intuition /intuition.h” 


UBYTE escdata[| = { Ox9b, ’@’, 
Ox9b, ’A’, 
Ox9b, ’B’, 
Ox9b, ’C’, 
Ox9b, ’D’, 
Ox9b, ’E’, 
Ox9b, ’F’, 
Ox9b, ’J’, 
Ox9b, ’K’, 
Ox9b, ’L’, 
Ox9b, "M’, 
Ox9b, ’P’, 
Ox9b, ’S’, 
Ox9b, ’T’, 
Oxlb, ’c’, 
Ox9b, ’q’, 
Ox9b, ’n’, 
Ox9b,’’, ’p’ 
Ox9b, 

Ox9b, 


» PP, 
0’, ) “ Dp’, 
Ox9b, 
} 


Op? ITV? IRD 
2,0’, *h’, 
96)? ITV? 779 
2-0. 1, 


) 


/* insert character */ 

/* cursor up */ 

/* cursor down */ 

/* cursor left */ 

/* cursor right */ 

/* cursor next line */ 

/* cursor prev line */ 

/* erase to end of display */ 
/* erase to end of line */ 
/* insert line */ 

/* delete line */ 

/* delete character */ 

/* scroll up */ 

/* scroll down */ 

/* reset to initial state */ 
/* window status request */ 
/* device status report */ 
/* cursor on */ 

/* cursor off */ 

/* set mode */ 

/* reset mode */ 


/* COVER A SELECTED SUBSET OF THE CONSOLE AVAILABLE FUNCTIONS */ 


#define INSERTCHARSTRING 
#define CURSUPSTRING 
#define CURSDOWNSTRING 
#-define CURSFWDSTRING 
#define CURSBAKSTRING 
#define CURSNEXTLINE 
#define CURSPREVLINE 
#define ERASEEODSTRING 
#define ERASEEOLSTRING 
#define INSERTLINESTRING 
#define DELETELINESTRING 
#-define DELCHARSTRING 
#define SCROLLUPSTRING 
#-define SCROLLDOWNSTRING 
#define RESETINITSTRING 


#define WINDOWSTATSTRING 


&escdata|0| 
&escdata|0+2] 
&escdata|0+4] 
&escdata|0+6| 
&escdata/0+8] 
&escdata[0+10] 
‘&escdata/0+12] 
&escdata|0+14| 
&escdata|0+16] 
&escdata|0+18] 
&escdata|0+20] 
&escdata/0+22] 
S&escdata|0+24| 
&escdata|0+26| 
&escdata[0+28] 
&escdata|0+30] 
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#define DEVSTATSTRING 
#define CURSONSTRING 
#define CURSOFFSTRING 
#define SETMODESTRING 
#define RESETMODESTRING 


#define BACKSPACE(r) 
#-define TAB(r) 

#define LINEFEED(r) 
#define VERTICALTAB(r) 
#define FORMFEED(r) 
#define CR(r) 

#define SHIFTOUT(r) 
#define SHIFTIN(r) 
#define CLEARSCREEN(r) 


#define RESET(r) 

#define INSERT(r) 
#define CURSUP(r) 
#define CURSDOWN(r) 
#define CURSF WD(r) 
#define CURSBAK(r) 
#define CURSNEXTLN(r) 
#define CURSPREVLN(r) 
#define ERASEEOD(r) 
#define ERASEEOL(r) 
#define INSERTLINE(r) 
#define DELETELINE(r) 
#define SCROLLUP(r) 
#define SCROLLDOWN(r) 
#define DEVICESTATUS(r) 
#define WINDOWSTATUS(r) 
#define DELCHAR(r) 
#define CURSORON(r) 
#define CURSOROFF(r) 
#define SETMODE(r) 
#define RESETMODE(r) 


#-define CloseConsole(r) 
ULONG DosBase; 
ULONG DiskfontBase; 


ULONG IntuitionBase; 
ULONG GfxBase; 
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S&escdata|0+32| 
&escdata|0+34| 
&escdata|0+37| 
S&escdata|0+41| 
&escdata|0+45] 


ConPutChar(r,0x08) 
ConPutChar(r,0x09) 
ConPutChar(r,0x0a) 
ConPutChar(r,0x0b) 
ConPutChar(r,0x0c) 
ConPutChar(r,0x0d) 
ConPutChar(r,0x0e) 
ConPutChar(r,0x0f) 
ConPutChar(r,0x0c) 


Con Write(r,RESETINITSTRING, 2) 
ConWrite(r, INSERTCHARSTRING,2) 
Con Write(r,CURSUPSTRING,2) 

Con Write(r, CURSDOWNSTRING,2) 
Con Write(r, CURSF WDSTRING,2) 
Con Write(r, CURSBAKSTRING,2) 
Con Write(r, CURSNEXTLINE,2) 
ConWrite(r, CURSPREVLINE,2) 

Con Write(r, ERASEEODSTRING,2) 
Con Write(r, ERASEEOLSTRING,2) 
Con Write(r, INSERTLINESTRING,2) 
Con Write(r, DELETELINESTRING,2) 
Con Write(r, SCROLLUPSTRING,2) 
Con Write(r, SCROLLDOWNSTRING,2) 
ConWrite(r,DEVSTATSTRING,2) 
Con Write(r, WINDOWSTATSTRING, 2) 
Con Write(r, DELCHARSTRING,2) 
ConWrite(r, CURSONSTRING,3) 
ConWrite(r, CURSOFFSTRING,4) 
Con Write(r, SETMODESTRING, 4) 
Con Write(r, RESETMODESTRING, 4) 


CloseDevice(r) 


struct NewWindow nw = { 


10, 10, /* starting position (left,top) */ 
620,90, /* width, height */ 

-1,-1, /* detailpen, blockpen */ 

0 /* flags for idcmp */ 


WINDOWDEPTH]|WINDOWSIZING|WINDOWDRAG|SIMPLE_REFRESH 
|ACTIVATE|GIMMEZEROZERO, /* window gadget flags */ 


O, /* pointer to Ist user gadget */ 
NULL, /* pointer to user check */ 
”Console Test”, /* title */ 

NULL, /* pointer to window screen */ 
NULL, /* pointer to super bitmap */ 
100,45, /* min width, height */ 
640,200, /* max width, height */ 
WBENCHSCREEN}; 


struct Window *w; 
struct RastPort *rp; 


struct IOStdReq *consoleWriteMsg;  /* I/O request block pointer */ 


struct MsgPort *consoleWritePort; /* a port at which to receive */ 
struct IOStdReq *consoleReadMsg; /* I/O request block pointer */ 
struct MsgPort *consoleReadPort; /* a port at which to receive */ 


extern struct MsgPort *CreatePort(); 
extern struct I[OStdReq *CreateStdIO(); 


char readstring|200];  /* provides a buffer even though using only one char */ 


main() 


{ 


SHORT 1; 
SHORT status; 
SHORT problem; 
SHORT error; 
problem — QO; 


if((DosBase = OpenLibrary(” dos.library”, 0)) =— NULL) 
{ problem = 1; goto cleanup]; } 
if((DiskfontBase—OpenLibrary(” diskfont.library” ,0))=—NULL) 
{ problem = 2; goto cleanup2; } 
if((IntuitionBase=OpenLibrary(” intuition. library” ,0))—=—NULL) 
{ problem = 3; goto cleanup3; } 
if((GfxBase—OpenLibrary(” graphics.library” ,0))——NULL) 
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{ problem = 4; goto cleanup4; } 


consoleWritePort = CreatePort(” my.con.write” ,O); 
if(consoleWritePort == 0) 

{ problem = 5; goto cleanup5; } 
consoleWriteMsg = CreateStdIO(consoleWritePort); 
if(consoleWritePort == 0) 

{ problem = 6; goto cleanup6; } 


consoleReadPort = CreatePort(” my.con.read” ,O); 
if(consoleReadPort == 0) 

{ problem = 7; goto cleanup7; } 
consoleReadMsg = CreateStdIO(consoleReadPort); 
if(consoleReadPort == 0) 

{ problem = 8; goto cleanup8; } 


w = (struct Window *)OpenWindow(&nw); /* create a window */ 
if(w == NULL) 
{ problem = 9; goto cleanup9; } 


rp = w->RPort; /* establish its rastport for later */ 


/* 7K OK OK 2K 2 2 EK EK 2 2K 2K 2K 2 KK 2K eK 2 2 2 2k 2 2 2K 2 2 2K 2K 2 KK 2 2c 2 2 2 2h 2 KK EK 2 2 2K 2 2 2 2 2 fe ie ote 2g 2 2 2 ok 6 Ek + / 


/* NOW, Begin using the actual console macros defined above. + / 
[ROBBIE AGG E COGS EE IIA CI ICICI ER aE / 


error = OpenConsole(consoleWriteMsg,consoleReadMsg,w); 
if(error != 0) 

{ problem = 10; goto cleanup10; } 

/* attach a console to this window, initialize 

* for both write and read */ 


QueueRead(consoleReadMsg, &readstring(0]); /* tell console where to 
* put a character that 
* it wants to give me 


* and queue up first read */ 
ConWrite(console WriteMsg,” Hello, World\r\n” 14); 


ConPutStr(consoleWriteMsg,” testing BACKSPACE” ); 
for(i=0; 1<10; i++) 

{ BACKSPACE(consoleWriteMsg); Delay(30); } 
ConPutStr(consoleWriteMsg,” \r\n” ); 


ConPutStr(consoleWriteMsg,” testing TAB\r”); 
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for(i=0; 1<6; i++) 
{ TAB(consoleWriteMsg); Delay(30); } 


ConPutStr(consoleWriteMsg,” \r\n” ); 


ConPutStr(consoleWriteMsg,” testing LINEFEED\r”); 
for(i=0; i<4; i++) 
{ LINEFEED(consoleWriteMsg); Delay(30); } 


ConPutStr(consoleWriteMsg,” \r\n” ); 


ConPutStr(consoleWriteMsg,” testing VERTICALTAB\r”); 
for(i=0; 1<4; i++) 
{ VERTICALTAB(consoleWriteMsg); Delay(30); } 


ConPutStr(consoleWriteMsg,” \r\n” ); 


ConPutStr(consoleWriteMsg,” testing FORMFEED\r” ); 
Delay(30); 
for(i=0; 1<2; i++) 

{ FORMFEED(consoleWriteMsg); Delay(30); } 


ConPutStr(consoleWriteMsg,” \r\n” ); 


ConPutStr(consoleWriteMsg,” testing CR”); 
Delay(30); 

CR(consoleWriteMsg); 

Delay(60); 

ConPutStr(consoleWriteMsg,” \r\n” ); 


ConPutStr(consoleWriteMsg,” testing INSERT\r”); 
for(i=0; i<4; i++) 

{ INSERT(consoleWriteMsg); Delay(30); } 
ConPutStr(consoleWriteMsg,” \r\n” ); 
ConPutStr(consoleWriteMsg,” testing DELCHAR\r” ); 
CR(consoleWriteMsg); 
for(i=O0; 1<4; i++) 

{ DELCHAR(consoleWriteMsg); Delay(30); } 
ConPutStr(consoleWriteMsg,” \r\n” ); 


ConPutStr(consoleWriteMsg,” testing INSERTLINE\r” ); 
CR(consoleWriteMsg); 
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for(i=0; i<3; i++) 
{ INSERTLINE(consoleWriteMsg); Delay(30); } 
ConPutStr(consoleWriteMsg,” \r\n” ); 


ConPutStr(consoleWriteMsg,” testing DELETELINE\r’ ); 
CR(consoleWriteMsg); 
LINEFEED(consoleWriteMsg); 
Delay(60); 
for(i=0; 1<4; i++) 

{ DELETELINE(consoleWriteMsg); Delay(30); } 
ConPutStr(consoleWriteMsg,” \r\n” ); 


ConPutStr(consoleWriteMsg,” testing CURSUP\r” ); 
for(i=0; 1<4; i++) 

{ CURSUP(consoleWriteMsg); Delay(30); } 
ConPutStr(consoleWriteMsg,” \r\n” ); 
ConPutStr(consoleWriteMsg,” testing CURSDOWN\r”); 
for(i=0; 1<4; i++) 

{ CURSDOWN(consoleWriteMsg); Delay(30); } 
ConPutStr(consoleWriteMsg,” \r\n” ); 
ConPutStr(consoleWriteMsg,” testing CURSF WD\r”); 
for(i=0; i<4; i++) 

{ CURSFWD(consoleWriteMsg); Delay(30); } 
ConPutStr(consoleWriteMsg,” \r\n” ); 
ConPutStr(consoleWriteMsg,” testing CURSBAK”); 
for(i=0; 1<4; i++) 

{ CURSBAK(consoleWriteMsg); Delay(30); } 
ConPutStr(consoleWriteMsg,” \r\n” ); 
ConPutStr(consoleWriteMsg,” testing CURSPREVLN?” ); 
for(i=0; i<4; i++) 

{ CURSPREVLN(consoleWriteMsg); Delay(30); } 
ConPutStr(consoleWriteMsg,” \r\n” ); 
ConPutStr(consoleWriteMsg,” testing CURSNEXTLN”); 


for(i=0; 1<4; i++) 
{ CURSNEXTLN(consoleWriteMsg); Delay(30); } 
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ConPutStr(consoleWriteMsg,” \r\n” ); 


ConPutStr(consoleWriteMsg,” testing ERASEEOD”); 
CURSPREVLN(consoleWriteMsg); 
CURSPREVLN(consoleWriteMsg); 
CURSPREVLN(consoleWriteMsg); 
Delay (60); 
for(i=0; 1<4; i++) 

{ ERASEEOD(consoleWriteMsg); Delay(30); } 


ConPutStr(consoleWriteMsg,” \r\n” ); 


ConPutStr(consoleWriteMsg,” testing ERASEEOL. junk”); 
CURSBAK(consoleWriteMsg); 
CURSBAK(consoleWriteMsg); 
CURSBAK(consoleWriteMsg); 
( ) 
( ) 


) 


CURSBAK(consoleWriteMsg 
CURSBAK(consoleWriteMsg 
Delay(60); 
ERASEEOL(consoleWriteMsg); 
Delay(30); 
ConPutStr(consoleWriteMsg,” \r\n” ); 


) 


ConPutStr(consoleWriteMsg,” testing SCROLLUP”); 
for(i=0; i<4; i++) 
{ SCROLLUP(consoleWriteMsg); Delay(30); } 


ConPutStr(consoleWriteMsg,” \r\n” ); 
ConPutStr(consoleWriteMsg,” testing SCROLLDOWN?”); 
ConPutStr(consoleWriteMsg,” \n\n\n” ); 
for(i=0; 1<4; i++) 

{ SCROLLDOWN(consoleWriteMsg); Delay(30); } 


ConPutStr(consoleWriteMsg,” \r\n”); 


ConPutStr(consoleWriteMsg,” testing CURSOROFF” ); 
CURSOROFF(consoleWriteMsg); 
ConPutStr(consoleWriteMsg, ” printed.with.cursor.off” ); 
Delay(60); 

ConPutStr(consoleWriteMsg,” \r\n” ); 


CURSORON(consoleWriteMsg); Delay(30); 
ConPutStr(consoleWriteMsg,” testing CURSORON?” ); 
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/* OOO RO IO oR km kok kk aR kk ak ak a kok ak * / 


Delay(120); /* wait 2 seconds (120/60 ticks) */ 


status = CheckIO(consoleReadMsg); /* see if console read 

* anything, abort if not */ 
if(status =— FALSE) AbortIO(consoleRead Msg); 
WaitPort(consoleRead Port); /* wait for abort to complete */ 
GetMsg(consoleRead Port); /* and strip message from port */ 


CloseConsole(console WriteMsg); 
cleanupl0: 
cleanup9: 
CloseWindow(w); 
cleanup8: 
DeleteStdIO(consoleRead Msg); 
cleanup7: 
DeletePort(consoleReadPort); 
cleanup6: 
DeleteStdIO(consoleWriteMsg); 
cleanups: 
DeletePort(consoleWritePort); 
cleanup4: 
CloseLibrary(GfxBase); 
cleanups: 
CloseLibrary(IntuitionBase); 
cleanup2: 
CloseLibrary(DiskfontBase); 
cleanupl: 
CloseLibrary(DosBase); 
if(problem > 0) exit(problem+1000); 
else 
return(0); 


} /* end of main() */ 


/* Open a console device */ 


/* this function returns a value of 0 if the console 
* device opened correctly and a nonzero value (the error 
* returned from OpenDevice) if there was an error. 


vi 


int 
OpenConsole(writerequest,readrequest, window) 
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struct IOStdReq *writerequest; 
struct IOStdReq *readrequest; 
struct Window *window; 


{ 


} 


int error; 

writerequest- >io_Data = (APTR) window; 
writerequest- >io_Length = sizeof(*window); 

error = OpenDevice(” console.device”, 0, writerequest, 0); 
readrequest- >10_Device = writerequest- >io_Device; 


readrequest- >io_Unit = writerequest->io_Unit; 
/* clone required parts of the request */ 
return(error); 


/* Output a single character to a specified console */ 


int 


ConPutChar(request,character) 
struct IOStdReq *request; 
char character; 


{ 


} 


request- >10_Command = CMD_WRITE; 
request- >io_Data = (APTR)&character; 
request- >1i0_Length = 1; 
DolO(request); 
/* command works because DolO blocks until command is 
* done (otherwise pointer to the character could become 
* invalid in the meantime). 
* 
/ 


return(0); 


/* Output a stream of known length to a console */ 


int 


Con Write(request,string,length) 
struct LOStdReq *request; 
char *string; 
int length; 


{ 


request- >10_Command = CMD_WRITE; 
request- >io_Data = (APTR)string; 
request- >io_Length = length; 
DolO(request); 


/* command works because DolO blocks until command is 
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* done (otherwise pointer to string could become 
* invalid in the meantime). 

ry 

return(0); 


j 
/* Output a NULL-terminated string of characters to a console */ 


int 
ConPutStr(request,string) 

struct IOStdReq *request; 

char *string; 

{ 
request- >10_Command = CMD_WRITE; 
request- >io_Data = (APTR)string; 
request- >io_Length = -1; /* tells console to end when it sees 

* a terminating zero on the string. */ 

DolO(request); 
return(0); 


} 


/* queue up a read request to a console, show where to put the 
* character when ready to be returned. Most efficient if this is 
* called right after console is opened */ 


int 
QueueRead(request, whereto) 

struct IOStdReq *request; 

char *whereto; 

{ 
request- >i0o_Command = CMD_READ; 
request->io_Data = (APTR)whereto; 
request- >10_Length = 1; 
SendIO(request); 
return(0); 


j 


/* see if there is a character to read. If none, don’t wait, 
* come back with a value of -1 */ 


int 

ConMay GetChar(request,requestPort, whereto) 
struct IOStdReq *request; 
char *whereto; 


{ 
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register temp; 


if ( GetMsg(requestPort) == NULL ) return(-1); 
temp = *whereto; 

QueueRead(request, whereto); 

return(temp); 


} 


/* go and get a character; put the task to sleep if 
* there isn’t one present */ 


UBYTE 
ConGetChar(consolePort,request, whereto) 
struct IOStdReq *request; 
struct MsgPort *consolePoft; 
char *whereto; 
{ 
register UBYTE temp; 
while((GetMsg(consolePort) === NULL)) WaitPort(consolePort); 


temp = *whereto; /* get the character */ 
QueueRead(request, whereto):; 
return(temp); 
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Chapter 9 


Input Device 


This chapter describes the Amiga input device, which is a combination of three other 
devices: keyboard device, gameport device, and timer device. The input device merges separate 
input event streams from the keyboard, mouse, and timer into a single stream. This single 


stream can then be interpreted by the prioritized linked list of input handlers that are watching 
the input stream. 


Note that two additional messages can appear in the input stream: “‘disk inserted’’ and “disk 


removed.” These messages come from AmigaDOS and are sent to the input device for further 
propagation. 
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Introduction 


The input device is automatically opened by AmigaDOS by any call to open the console device. 
When the input device is opened, a task, appropriately named “‘input.device’’, is started. The 
input device task communicates directly with the keyboard device to obtain raw key inputs. It 
also communicates with the gameport device to obtain mouse button and mouse movement 
events and with the timer device to obtain time events. In addition to these event streams, you 
can also directly input an event to the input device, to be fed to the handler chain. This topic 
is also covered below. 


The keyboard device is also accessible directly (see chapter 10). However, while the input device 


task is operating, that task attempts to retrieve all incoming keyboard events and add them to 
the input stream. 


The gameport device has two units. As you view the Amiga, looking at the gameport connec- 
tors, connector ‘‘l”’ is assigned as the primary mouse input for Intuition and contributes 
gameport input events to the input event stream. Connector ‘‘2”’ is handled by the other 
gameport unit and is currently unassigned. Each unit of the gameport device is an exclusive 
access object, in that you can specify what type of controller is attached. It is then assumed 
that only one task is sending requests for input from that unit. While the input device task is 
running, that task expects to read the input from connector 1. Direct use of the gameport dev- 
ice is covered in a separate chapter of this manual. 


The timer device provides time events for the input device. It also provides time interval reports 
for controlling key repeat rate and key repeat threshold. The timer device is a shared-access 
device and is described in its own separate chapter. 


Input Device Commands 


The input device allows the following system functions: 


Command Operation 


OpenDevice() Obtain shared use of the input device 
CloseDevice() Relinquish use of the input device 


DoIO() Initiate a command, and wait for it to complete 
SendIO() Initiate a command, and return immediately 
AbortIO() Abort a command already in the queue 
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Only the Start, Stop, Invalid, and Flush commands have been implemented for this device. All 
other commands are no-operations. 


The input device also supports the device-specific commands shown in table 9-1. 


I/O Command 


IND_WRITEEVENT 
IND_ADDHANDLER 
IND_REMHANDLER 
IND_SETTHRESH 
IND_SETPERIOD 
IND_SETMPORT 
IND_SETMTRIG 


IND_SETMTYPE 


Table 9-1: Input Device Commands 


Operation 


Propagate an input event stream to all devices 
Add an input-stream handler into the handler chain 
Remove an input-stream handler from the handler chain 
Set the repeating key hold-down time before repeat starts 
Set the period at which a repeating key repeats. 
Set the gameport port to which the mouse is connected 
Read conditions that must be met by a mouse before 

a pending read request will be satisfied 
Set the type of device at the mouse port 


The device-specific commands outlined above are described in the following paragraphs. A 
description of the contents of an input event is given first because the input device deals in 
input events. An input event is a data structure that describes the following: 


O 


O 


The class of the event—often describes the device that generated the event 


The subclass of the event —space for more information if needed 


The code— keycode if keyboard, button information if mouse, others 


A qualifier such as “Alt key also down,”’ “key repeat active”’ 


A position field that contains a data address or a mouse position count 


A time stamp, showing the sequence in which events have occurred 


A link-field by which input events are linked together 


The various types of input events are listed in the include file devices/inputevent.h. That infor- 
mation is not repeated here. You can find more information about input events in the chapters 
titled ‘““Gameport Device’’ and ‘‘Console Device.”’ 


There is a difference between simply receiving an input event from a device (gameport, key- 
board, or console) and actually becoming a handler of an input event stream. A handler is a 
routine that is passed an input event, and it is up to the handler to decide if it can process the 
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input event. If the handler does not recognize the event, it passes the address of the event as a 
return value. 


Because of the input event field called ie_ NextEvent, it is possible for the input event to be a 
pointer to the first event in a linked list of events to be handled. Thus, the handler should be 
designed to handle multiple events if such a link is used. Note that handlers can themselves 
generate new linked lists of events which can be passed down to lower priority handlers. 


IND_ADDHANDLER COMMAND 


You add a handler to the chain using the command IND_ADDHANDLER. Assuming that you 
have a properly initialized an IOStdReq block as a result of a call to OpenDevice() (for the 
input device), here is a typical C-language call to the IND-ADDHANDLER function: 


struct Interrupt handlerStuff; 
handlerStuff.is_Data = &hsData; 

/* address of its data area */ 
handlerStuff.is_Code = myhandler; 

/* address of entry point to handler */ 
handlerStuff.is_Node.lIn_Pri = 51; 

/* set the priority one step higher than Intuition, so that our 

* handler enters the chain ahead of Intuition. 

a 

/ 

inputRequestBlock.io_Command = IND_ADDHANDLER; 
inputRequestBlock.io_Data = &handlerStuff; 


DolIO(&inputRequestBlock); 
Notice from the above that Intuition is one of the input device handlers and normally distri- 
butes all of the input events. Intuition inserts itself at priority position 50. You can choose the 
position in the chain at which your handler will be inserted by setting the priority field in the 
list-node part of the interrupt data structure you are feeding to this routine. 
Note also that any processing time expended by a handler subtracts from the time available 


before the next event happens. Therefore, handlers for the input stream must be fast. 


Rules for Input Device Handlers 


The following rules should be followed when you are designing an input handler: 
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o If an input handler is capable of processing a specific kind of an input event and that 
event has no links (ie_NextEvent = 0), the handler can end the handler chain by 
returning a NULL (0) value. 


o If there are multiple events linked together, the handler is free to delink an event from 


the input event chain, thereby passing a shorter list of events to subsequent handlers. 
The starting address of the modified list is the return value. 


o If a handler wishes to add new events to the chain that it passes to a lower-priority 
handler, it may initialize memory to contain the new event or event chain. The 
handler, when it again gets control on the next round of event handling, should assume 
nothing about the current contents of the memory blocks it attached to the event 
chain. Lower priority handlers may have modified the memory as they handled their 
part of the event. The handler that allocates the memory for this purpose should keep 
track of the starting address and the size of this memory chunk so that the memory can 
be returned to the free memory list when it is no longer needed. 


Your routine should be structured so that it can be called as though from the following C- 
language statement: 


newEventChain = yourHandlerCode(oldEventChain, yourHandlerData); 
where 
o yourHandlerCode is the entry point to your routine 
o oldEventChain is the starting address for the current chain of input events 


o newEventChain is the starting address of an event chain which you are passing to the 
next handler, if any 


A NULL (0) value terminates the handling. 


Memory that you use to describe a new input event that you have added to the event chain 1s 
available for reuse or deallocation when the handler is called again or after the 


IND_REMHANDLER command for the handler is complete. 
Because IND_ADDHANDLER installs a handler in any position in the handler chain, it can, for 


example, ignore specific types of input events as well as act upon and modify existing streams of 
input. It can even create new input events for Intuition or other programs to interpret. 
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IND_REMHANDLER COMMAND 


You remove a handler from the handler chain with the command IND _REMHANDLER. 
Assuming that you have a properly initialized [OStdReq block as a result of a call to 
OpenDevice() (for the input device) and you have already added the handler using 
IND_ADDHANDLER, here is a typical C-language call to the IND-REMHANDLER function: 


inputRequestBlock.io_ Command = IND_REMHANDLER; 
inputRequestBlock.io_Data = &handlerStuff; 
/* tell it which one to remove */ 


DolO(&inputRequestBlock); 


IND_WRITEEVENT COMMAND 


As noted in the overview of this chapter, input events are normally generated by the timer dev- 
ice, keyboard device or gameport device. A user can also generate an input event and send it to 
the input device. It will then be treated as any other event and passed through to the input 
handler chain. You can create your own stream of events and then send them to the input dev- 
ice using the IND_WRITEEVENT command. Here is an example, assuming a correctly initial- 


ized input_request_block. The example sends in a single event, which is a phony mouse- 
movement: 


struct InputEvent phony; 


input_request_block.io_Command = IND_WRITEEVENT; 
input_request_block.io_Flags = 0; 
input_request_block.io_Length = sizeof(struct InputEvent); 
input_request_block.io_Data = &phony; 


phony.ie_NextEvent = NULL; /* only one */ 
phony.ie_Class = IECLASS_RAWMOUSE; 
phony.ie_TimeStamp.tv_secs = 0; 
phony.ie_TimeStamp.tv_micro = 0; 
phony.ie_Code = IEFCODE_NOBUTTON; 
phony.ie_Qualifier = IFEQUALIFIER_RELATIVEMOUSE; 
phony.ie_X = 10; 
phony.ie_Y = 5; 
/* mouse didn’t move, but program made system think that it did. */ 
DolIO(&input_request_block); 


Note: This command adds the input event to the end of the current event stream. The system 


links other events onto the end of this event, thus modifying the contents of the data structure 
you constructed in the first place. 
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IND_SETTHRESH COMMAND 


This command sets the timing in seconds and microseconds for the input device to indicate how 
long a user must hold down a key before it begins to repeat. This command is normally per- 
formed by the Preferences tool or by Intuition when it notices that the Preferences have been 
changed. If you wish, you can call this function. The following typical sequence assumes that 


you have already correctly initialized the request block by opening the input device. Only the 
fields shown here need be initialized. 


struct InputEvent thresh_event; 


input_request_block.io_Command = IND_SETTHRESH; 
input_request_block.io_Flags = 0; 
input_request_block.io_Data = &thresh_event; 


thresh_event.ie_NextEvent = 0; 
thresh_event.ie_TimeStamp.tv_secs = 1; /* one second */ 
thresh_event.ie_TimeStamp.tv_micro = 500000; 

/* 500,000 microseconds = 1/2 second */ 
DolIO(&input_request_block); 


IND_SETPERIOD COMMAND 


This command sets the time period between key repeat events once the initial period threshold 
has elapsed. Again, it is a command normally issued by Intuition and preset by the Preferences 


tool. A typical calling sequence is as shown above; change the command number and the timing 
period values to suit your application. 


Input Device and Intuition 


There are several ways to receive information from the various devices that are part of the 
input device. The first way is to communicate directly with the device. This way is, as 
specified above, occasionally undesirable (while the input device task is running). The second 


way is to become a handler for the stream of events which the input device produces. That 
method is also shown above. 


The third method of getting input from the input device is to retrieve the data from the console 
device or from the IDCMP (Intuition Direct Communications Message Port). 
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If you choose this third method, you should be aware of what happens to input events if your 
task chooses not to respond to them. If there is no active window and no active console, then 
input events (keystrokes or left-button mouse clicks usually) will simply be ignored. If, how- 
ever, there is an active window (yours), and you choose to simply let the messages pile up 
without responding to them as quickly as possible, here is what happens: 


o Another event occurs. If the system has no empty message that it can fill in to report 
this new event, then memory is dynamically allocated to hold this new information and 
the new message is transmitted to the message port for the task. 


o When the task finally responds to the message, the allocated memory is not returned to 
the system until the window is closed. Therefore, a task that chooses not to respond to 
its incoming messages for a long period of time can potentially remove a great deal of 
memory from the system free-memory list, making that memory space unavailable to 
this or other tasks until this task is completed. 


Thus it 1s always a good idea to respond to input messages as quickly as possible to maximize 
the amount of free memory in the system while your task is running. 


Sample Program 


/* Sample program for adding an input handler to the input stream 
* Note that compiling this program native on the Amiga requires 
* a separate compile for this program, a separate assembly for the 
* handler.interface.asm, and a separate alink phase. Alink will 
* be used to tie together the object files produced by the separate 
* language phases. If compiling under Amiga C, disable stack checking 
* code in pass 2 of the compiler ( e.g., lc2 -v filename.q). 
k 

Linking information: 

inputdev.with: 


TO inputdev 
LIBRARY lhib:le.lib, ib:amiga.lib 


- 


ok 
* 
* 
* FROM lib:Lstartup.obj,inputdev.o, input.timerstuff.o, handler.interface.o 
* 
* 


#include <exec/types.h > 
#include <exec/ports.h > 
#include <exec/memory.h> 
#include <exec/io.h> 
#include <exec/tasks.h > 
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#include <exec/interrupts.h > 
#include <devices/input.h> 
#include <exec/devices.h > 
#include <devices/inputevent.h > 


#define FIKEYUP OxDO 
struct InputEvent copyevent; /* local copy of the event */ 
/* assumes never has a next.event attached */ 
struct MsgPort *inputDevPort; 
struct I[OStdReq *inputRequestBlock; 
struct Interrupt handlerStuff; 


struct InputEvent dummyEvent; 


extern struct MsgPort *CreatePort(); 
extern struct I[OStdReq *CreateStdIO(); 


struct MemEntry me([10]; 


/* If we want the input handler itself to add anything to the 

* input stream, we will have to keep track of any dynamically 

* allocated memory so that we can later return it to the system. 
* Other handlers can break any internal links the handler puts 
* in before it passes the input events. 


+) 


struct InputEvent 

*myhandler(ev, mydata) 
struct InputEvent *ev;/* and a pointer to a list of events */ 
struct MemEntry *mydatal||; 
/* system will pass me a pointer to my own data space. */ 


/* Demo version of program simply reports input events as 
* its sees them; passes them on unchanged. Also, if there 
* is a linked chain of input events, reports only the lead 
* one in the chain, for simplicity. 
+) 

if(ev- >ie_Class === IECLASS_TIMER) 


} 


/* don’t try to print timer events!!! they come every 1/10th sec. */ 
else 


return(ev); 


Forbid(); /* don’t allow a mix of events to be reported */ 


Input Device 329 


copyevent.ie_Class = ev- >1e_Class; 

copyevent.ie_SubClass = ev->ie_SubClass; 

copyevent.ie_Code = ev->1e_Code; 

copyevent.ie_Qualifier = ev- >ie_Qualifier; 

copyevent.le_X == ev->1ie_X; 

copyevent.ie_Y = ev->1e_Y; 

copyevent.ie_TimeStamp.tv_secs = ev->1e_TimeStamp.tv_secs; 
copyevent.ie_TimeStamp.tv_micro = ev- >ie_TimeStamp.tv_micro; 
Permit(); 


} 


/* There will be lots of events coming through here; 

* rather than make the system slow down because something 
* is busy printing the previous event, let’s just print what 

* we find is current, and if we miss a few, so be it. 

* 

* Normally this loop would ”handle” the event or perhaps 

* add a new one to the stream. (At this level, the only 

* events you should really be adding are mouse, rawkey or timer, 
* because you are ahead of the intuition interpreter.) 

* No printing is done in this loop (lets main() do it) because 
* printf can’t be done by anything less than a ’process’ 
return(ev); 

/* pass on the pointer to the event (most handlers would 

* pass on a pointer to a changed or an unchanged stream) 

* (we are simply reporting what is seen, not trying to 

* modify it in any way) */ 


} 


/* NOTICE: THIS PROGRAM LINKS ITSELF INTO THE INPUT STREAM AHEAD OF 
* INTUITION. THEREFORE THE ONLY INPUT EVENTS THAT IT WILL SEE AT 

* ALL ARE TIMER, KEYBOARD AND GAMEPORT. AS NOTED IN THE PROGRAM, 
* THE TIMER EVENTS ARE IGNORED DELIBERATELY */ 


extern struct Task *FindTask(); 
struct Task *mytask; 

LONG mysignal; 

extern VOID HandlerInterface(); 


struct timerequest *mytimerRequest; 
extern struct timerequest *PrepareTimer(); 


extern int WaitTimer(); 
extern int DeleteTimer(); 
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main() 


{ 


SHORT error; 
ULONG oldseconds, oldmicro, oldclass; 


/* init dummy event, this is what we will feed to other handlers 
* while this handler is active */ 


dummyEvent.ie_Class = IECLASS_NULL; /* no event happened */ 
dummyEvent.ie_NextEvent = NULL; /* only this one in the chain */ 


inputDevPort — CreatePort(0,0); /* for input device */ 


if(inputDevPort =— NULL) exit(-1);  /* error during createport */ 
inputRequestBlock — CreateStdIO(inputDevPort); 
if(inputRequestBlock == 0) { DeletePort(inputDevPort); exit(-2); } 


/* error during createstdio */ 


mytimerRequest = PrepareTimer(); 
if(mytimerRequest === NULL) exit(-3); 


handlerStuff.is_Data = (APTR)&me(0); 

/* address of its data area */ 
handlerStuff.is_Code = HandlerInterface; 

/* address of entry point to handler */ 
handlerStuff.is_Node.In_Pri = 51; 

/* set the priority one step higher than 

* Intuition, so that our handler enters 

* the chain ahead of Intuition. 

+) 
error = OpenDevice(” input.device” ,O,inputRequestBlock,0); 
if(error == 0) printf(”\nOpened the input device”); 


inputRequestBlock- >i0_Command = IND_ADDHANDLER; 
inputRequestBlock- >io_Data = (APTR)&handlerStuff; 


DolO(inputRequestBlock); 
copyevent.ie_TimeStamp.tv_secs = 0; 
copyevent.ie_TimeStamp.tv_micro = 0; 
copyevent.ie_Class = 0; 

oldseconds = QO; 

oldmicro = 0; 

oldclass —0; 


for(;;) /* FOREVER */ 
{ 
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WaitForTimer(mytimerRequest, 0, 100000); 
/* TRUE = wait; time = 1/10th second */ 


/* note: while this task is asleep, it is very very likely that 
* one or more events will indeed pass through the input handler. 
* This task will only print a few of them, but won’t intermix 
* the pieces of the input event itself because of the Forbid() 
* and Permit() (not allow task swapping when a data structure 
+ isn’t internally consistent) 
* 
/ 
if(copyevent.ie_Class === IECLASS_RAWKEY && copyevent.ie_Code == FIKEYUP) 


break; /* exit from forever */ 
else 
{ 
Forbid(); 
if(copyevent.ie_TimeStamp.tv_secs != oldseconds || 
copyevent.ie_TimeStamp.tv_micro !== oldmicro || 
copyevent.ie_Class != oldclass ) 


oldseconds = copyevent.ie_TimeStamp.tv_secs; 
oldmicro = copyevent.ie_TimeStamp.tv_micro; 
oldclass = copyevent.ie_Class; 
showEvents( &copyevent); 
} 
Permit(); 
} 
} 
/* Although this task sleeps (main loop), the handler is independently 
* called by the input device. 


a? 


/* For keystrokes that might be recognized by AmigaDOS, such as 
* alphabetic or numeric keys, you will notice that after the 

* first such keystroke, AmigaDOS appears to lock out your task 

* and accepts all legal keystrokes until you finally hit return. 

* This is absolutely true.... when both you and AmigaDOS try to 
* write into the same window, as is true if you run this program 

* from the CLI, the first keystroke recognized by AmigaDOS locks 
* the layer into which it is writing. Any other task trying 

* to write into this same layer is put to sleep. This allows 

* AmigaDOS to edit the input line and prevents other output to 
* that same window from upsetting the input line appearance. 

* In the same manner, while your task is sending a line of output, 


* AmigaDOS can be put to sleep it too must output at that time. 
* 
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* You can avoid this problem if you wish by opening up a separate 
* window and a console device attached to that window, and output 
* strings to that console. If you click the selection button on 

* this new window, then AmigaDOS won’t see the input and your 

* task will get to see all of the keystrokes. The other alternative 

* you can use, for demonstration sake, is to: 


* 

* 1. Make the AmigaDOS window slightly smaller in the 
* vertical direction. 

* 2. Then click in the Workbench screen area outside 

* of any window. 

* 


* Now there is no console device (particularly not AmigaDOS’s 
* console) receiving the raw key stream and your task will report 
* as many keystrokes as it can catch (while not sleeping, that is). 


+) 


/* remove the handler from the chain */ 
inputRequestBlock->io_Command = IND_REMHANDLER; 
inputRequestBlock- >io_Data = (APTR)&handlerStuff; 
DolO(inputRequestBlock); 


/* close the input device */ 
CloseDevice(inputRequestBlock); 


/* delete the IO request */ 
DeleteStdIO(inputRequestBlock); 


/* free other system stuff */ 
DeletePort(inputDevPort); 
DeleteTimer(mytimerRequest); 

\ /* end of main */ 


int 

showEvents(e) 

struct InputEvent *e; 

{ 
printf(” \n\nNew Input Event”); 
printf(” \nie_Class = %lx” ,e- >ie_Class); 
printf(” \nie_SubClass = %lx” ,e- >ie_SubClass); 
printf(” \nie_Code = %lx”, e->ie_Code); 
printf(” \nie_Qualifier = %lx” ,e- >ie_Qualifier); 
printf(”\nie_X = %ld”, e->ie_X); 

printf(”\nie_Y = %ld”, e->ie_Y); 

printf(”\nie_TimeStamp(seconds) = %lx”, e- >ie_TimeStamp.tv_secs); 
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return(0); 


} 


/* input.timerstuff.c */ 


# include 
# include 
#include 
#:include 
# include 
#include 
# include 
#include 
#include 
#include 
#-include 
#include 


” exec /types.h” 

” exec /nodes.h” 

” exec /lists.h” 
”exec/memory.h” 
” exec /interrupts.h” 
” exec /ports.h” 

” exec /libraries.h” 
” exec /io.h” 

” exec /tasks.h” 

” exec /execbase.h” 
” exec /devices.h” 

” devices /timer.h” 


extern struct MsgPort *CreatePort(); 
extern struct [ORequest *CreateExtIO(); 


struct timerequest 
+*PrepareTimer(precision) 


SHORT precision; 


{ 


/* return a pointer to a time request. If any problem, return NULL */ 


int error; 


SHORT whichunit; 


struct MsgPort *timerport; 
struct timerequest *timermsg; 


timerport = CreatePort(0,0); 
if (timerport == NULL) 


return(NULL); /* error during CreatePort */ 


timermsg = (struct timerequest *) 


CreateExtIO(timerport,sizeof(struct timerequest)); 


if (timermsg === NULL) 


{ 


DeletePort(timerport); 
return(NULL); /* error during CreateExtIO */ 


} 
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} 


int 


if(precision ) /* if true, use precision timer ( under 1 second ) */ 
whichunit = UNIT_MICROHZ; 


else 


whichunit = UNIT_VBLANK; 


error = OpenDevice(TIMERNAME, whichunit, timermsg, 0); 
if (error !== 0) 


DeleteExtIO(timermsg,sizeof(struct timerequest)); 
DeletePort(timerport); 

return(NULL); /* Error during OpenDevice */ 
} 


return(timermsg); 


WaitForTimer(tr,seconds,microseconds) 
ULONG seconds,microseconds; 
struct timerequest *tr; 


{ 


tr- >tr_node.io_Command = TR_ADDREQUEST; /* add a new timer request */ 


tr- >tr_time.tv_secs = seconds; /* seconds */ 
tr- > tr_time.tv_micro = microseconds; /* microseconds */ 
DolO( tr ); /* post request to the timer */ 
/* goes to sleep till done */ 
return(0); 
} 
int 
DeleteTimer(tr) 


struct timerequest *tr; 


{ 


struct MsgPort *tp; 


tp = tr->tr_node.io_Message.mn_Reply Port; 
if(tr !== 0) 


CloseDevice(tr); 
DeleteExtIO(tr,sizeof(struct timerequest)); 


j 

if(tp != 0) 
DeletePort(tp); 

return(0); 
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* handler.interface.asm 


Cette te tet eter Cet Steet eC err ret rr crt er eter erttrtterc rrr rrrererrr rere ts S. 
HandlerInterface() 


This code is needed to convert the calling sequence performed by 
the input.task for the input stream management into something 
that a C program can understand. 


This routine expects a pointer to an InputEvent in AO, a pointer 
to a data area in Al. These values are transferred to the stack 

in the order that a C program would need to find them. Since the 
actual handler is written in C, this works out fine. 


*¥ &* &* &* &* &F¥ F&F F&F FF F 


XREF _myhandler 
XDEF —_HandlerInterface 


_HandlerInterface: 
MOVEM.L  A0O/A1,-(A7) ; save registers 
JSR _myhandler_ ; go to the C language routine we provided 
ADDQ.L #8 ,A7 ; restore the registers on the way out. 
RTS 
END 
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Chapter 10 


Keyboard Device 


Introduction 


The keyboard device gives system access to the Amiga keyboard. When you send this device 
the command to read one or more keystrokes from the keyboard, for each keystroke (whether 
key-up or key-down) the keyboard device creates a data structure called an input event to 
describe what happened. A keyboard input event includes the key code (including up or down 
transition status), information about the current state of the left and right Shift keys, and 
whether the key came from the numeric keypad area. 
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Thus, the keyboard device provides more information than simply the “raw” key input that 
might be obtained by directly reading the hardware registers. In addition, the keyboard device 
can buffer keystrokes for you. If your task takes more time to process prior keystrokes, the key- 
board device senses additional keystrokes and saves several keystrokes as a type-ahead feature. 
If your task takes an exceptionally long time to read this information from the keyboard, any 
keystrokes queued up beyond the number the system can handle will be ignored. Normally, the 
input device task processes these keyboard events, turning them into input device events so that 
no keystrokes are lost. You can find more information about keyboard event-queuing in the 
chapter, ‘Input Device,’ in the topic titled “Input Device and Intuition.” 


Keyboard Device Commands 


The keyboard device allows the following system functions. The system functions operate 
normally. 


Command Operation 


OpenDevice() Obtain shared use of the keyboard device 
CloseDevice() Relinquish use of the keyboard device 


DoIO() Initiate a command, and wait for it to complete 
SendIO() Initiate a command, and return immediately 
AbortIO() Abort a command already in the queue 


The keyboard device also responds to the following commands: 


I/O Command Operation 


KBD_ADDRESETHANDLER Add a reset handler to the device 
KBD_REMRESETHANDLER Remove a reset handler from the device 
KBD_RESETHANDLERDONE _ Indicate that a handler has completed 
its job and reset could possibly occur now 
KBD_READMATRIX Read the state of every key in the keyboard 
KBD_READEVENT Read one (or more) key event from the 
keyboard device 
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KBD_ADDRESETHANDLER 


This command adds a routine to a chain of reset-handlers. When a user presses the key 
sequence Ctrl-left Amiga-right Amiga (the reset sequence), the keyboard device senses this and 
calls a prioritized chain of reset-handlers. These might be thought of as clean-up routines that 
‘“must’’ be performed before reset is allowed to occur. For example, if a disk write is in pro- 
gress, the system should finish that before resetting the hardware so as not to corrupt the con- 
tents of the disk. There are probably a few reasons why a program may wish to add its own 
reset handler as well. Note that if you add your own handler to this chain, you must ensure 
that your handler allows the rest of reset processing to occur. Reset must continue to function. 


You add a handler to the chain by the command KBD_ADDRESETHANDLER. Assuming that 
you have a properly initialized IOStdReq block as a result of a call to OpenDevice() (for the 
input device), here is a typical C-language call to the KBD_ADDRESETHANDLER function: 


struct Interrupt resetHandlerStuff; 
resetHandlerStuff.is_Data = &resetHandlerData; 

/* address of its data area */ 
resetHandlerStuff.is_Code = myResetHandler; 

/* address of entry point to handler */ 
resetHandlerStuff.is_Node.ln_Pri = myPriority; 
key boardRequestBlock.io_Command = KBD_ADDRESETHANDLER; 
key boardRequestBlock.io_Data = &resetHandlerStuff; 


DolIO(&key boardRequestBlock); 
The priority field in the list node structure establishes the sequence in which reset handlers are 


processed by the system. Your routine should be structured so that it can be called as though 
from the following C-language sequence: 


my ResetHandler(resetHandlerData); 


Any return value from this routine is ignored. All keyboard reset handlers are activated if time 
permits. 


The final command in your handler routine should be KBD_RESETHANDLERDONE, as 
described below. 


Note: Because of the time-critical nature of handlers, handlers are usually written in assembly 
code. However, keyboard reset processing can take a little longer and is therefore less critical if 
written in a language such as C. 


Keyboard Device 339 


KBD_REMRESETHANDLER 


This command is used to remove a keyboard reset handler from the system. The only difference 
from the calling sequence shown in KBD_ADDRESETHANDLER above is a change in the com- 
mand number to KBD_REMRESETHANDLER, and there is no need to specify the priority of 
the handler. 


KBD_RESETHANDLERDONE 


This command tells the system that this handler is finished with its essential activities. If this 
is the last handler in the chain, it completes the reset sequence. If not, the next handler in the 
chain gets its chance to function. 


Here is a typical statement sequence used to end a keyboard reset handler, again assuming a 
properly initialized inputRequestBlock: 


key boardRequestBlock.io_Command = KBD_RESETHANDLERDONE; 
key boardRequestBlock.io_Data = &resetHandlerStuff; 
SendIO(&keyboardRequestBlock); 

return; /* return so that other handlers can also do their jobs */ 


Note that SendIO() is used instead of DoIO(). This routine is being executed within a 
software interrupt, and it is illegal to allow a Wait() within such routines. 


KBD_READMATRIX 


This command lets you discover the current state (UP = 0, DOWN = 1) of every key in the 
key matrix. You provide a data area that is at least large enough to hold one bit per key, 
approximately 16 bytes. The keyboard layout is shown in figure 10-1 below, indicating the 
numeric value each transmits (raw) when it is pressed. This value is the numeric position that 
this key occupies in the key matrix read by this command. 
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Figure 10-1: Raw Key Matrix 


Assuming that you have already initialized an IOStdReq block for communication with the 
keyboard device, here is a typical calling sequence for sending the read-matrix command: 


UBYTE keyMatrix [16]; 
key boardRequestBlock.io_Command = KBD_READMATRIX; 
key boardRequestBlock.io_Data = &keyMatrix(0]; 
/* where to put the key matrix */ 
DolO(&key boardRequestBlock); 


To find the status of a particular key (for example, to find out if the F2 key is down), you find 
the bit that specifies the current state by dividing the key matrix value (hex 51 = decimal 81) 
by 8. This indicates that the bit is in byte number 10 of the matrix. Then take the same 
number (decimal 81) modulo 8 to determine which bit position within that byte represents the 
state of the key. This yields a value of 1. So, by reading bit position 1 of byte number 10, you 
determine the status of the function key F2. 


KBD_READEVENT 


Reading keyboard events is normally not done through direct access to the keyboard device. 
See chapter 9, “Input Device,” for the intimate linkage between that device and the keyboard 


device. This section is provided primarily to show you the component parts of a keyboard 
input event. 


The figure above shows the code value that each key places into the ie_Code field of the input 


event for a key down event. For a key-up event, a value of hexadecimal 80 is or’ed with the 
value shown above. Additionally, if either shift key is down, or if the key is one of those in the 
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numeric keypad, the qualifier field of the keyboard input event will be filled in accordingly. 


Note: The keyboard device can queue up several keystrokes without a task requesting a report 
of keyboard events. However, when the keyboard event buffer has been filled with no task 
interaction, additional keystrokes will be discarded. 


Example Keyboard Read-event Program 


Note: This sample program will run properly only if AmigaDOS and the input device are not 
active. 


/* sample program to demonstrate direct communications with the keyboard, 
* won’t work unless input device is disabled, so that keyboard can 

* be accessed individually. (It will compile and it will run, but 

* this program will get some of the keyboard’s inputs, and the input 

* device will steal the rest... no guarantee that Fl Key can break it out.) 

ok 

* ‘To try the program, if run under the AmigaDOS CLI, strike any key, then 
* hit return. (You won’t see any responses until each return key... DOS 

* is sitting on the input stream with its input editor as well as the 

* input device.) By rapidly hitting F1 then Return several times, 

* eventually you can generate a hex 50 that exits the program. This 

* program is provided for those who are taking over the machine. It 

* is not intended as a general purpose keyboard interface under DOS. 


+) 


#include <exec/types.h > 
#finclude <exec/io.h> 

#include <exec/devices.h > 
#include <devices/keyboard.h> 
#include <devices/inputevent.h > 


#define FIKEY 0x50 


extern struct MsgPort *CreatePort(); 
extern struct IOStdReq *CreateStdIO(); 


SHORT error; 
struct I[OStdReq *keyregq; 
struct MsgPort *keyport; 


struct InputEvent *keydata; /* pointer into the returned data area 
* where an input event has been sent */ 
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BYTE keybuffer|sizeof( struct InputEvent }|; 


main() 
{ 
keyport = CreatePort(0,0); 
if(key port == 0) { printf(”\nError during CreatePort” ); 
exit(-1); 
} 
keyreq = CreateStdlO(keyport); 
/* make an io request block for 
* communicating with the keyboard */ 
if(keyreq == 0) { printf(”\nError during CreateStdIO” ); 
DeletePort(keyport); 
exit(-2); 


error = OpenDevice(” keyboard.device” ,O,keyreq,0); 
/* open the device for access */ 


if (error != 0) { printf(”\nCan’t open keyboard!” ); 
ReturnMemory ToSystem(); 
exit(-100); 


keyreq->io_Length = sizeof(struct InputEvent); 
/* read one event each time we go back to the keyboard */ 


keyreq- >io_Data = (APTR)keybuffer; 
/* show where to put the data when read */ 


keydata = (struct InputEvent *)keybuffer; 


keyreq- >io_Command = KBD_READEVENT; __//* get an event!! */ 


for(;;) /* FOREVER */ 


printf(”\n Ready to retrieve another key0); 

DolO( keyreq ); 

if(keydata->ie_Code == F1IKEY) break; 

printf(”\n Raw key found this time was %|x” ,|keydata- > ie_Code); 


printf(”\nFINALLY found an F1 key!!! Exiting...”); 
ReturnMemoryToSystem(); /* can’t get here because of FOREVER, 


* but if user provides an exit..... */ 
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ReturnMemoryToSystem() 
DeleteStdIO(keyreq); 


DeletePort(key port); 
return(0); 


344 Keyboard Device 


Chapter 11 


Gameport Device 


Introduction 


The gameport device is the means of access to the Amiga gameports. There are two units in 
the gameport device. Unit 0 controls the front gameport connector (connector 1). Unit 1 con- 
trols the rear gameport connector (connector 2). 


You must tell the system the type of device connected to the gameport connector and how the 
device is to respond. That is, should the device return status immediately each time you ask for 
information or should it only return status once certain conditions have been met? 
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When the input device is operating, the left gameport connector is usually dedicated to that 
device. Therefore, this chapter’s examples concentrate on the right connector, which is not 
dedicated to the input device. Note that if the input device is not started, the left connector, as 
gameport unit 0, can perform the same functions as shown below for the right connector. 


When a gameport unit finally reponds to a request for input, it formulates an input event. The 


contents of the input event vary based on the type of device you have told the unit is connected 
and the trigger conditions it must look for. 


Gameport Device Commands 


The gameport device allows the following system functions. 


Command Operation 


OpenDevice() Obtain exclusive use of one unit of the gameport device. 
Returns an error value of -1 if another task already has 
control of the unit you have requested. 

CloseDevice() Relinquish use of the gameport device 


DoIO() Initiate a command and wait for it to complete 
SendIO() Initiate a command and return immediately 
AbortIO() Abort a command already in the queue 


The gameport device also responds to the following commands: 


I/O Command Operation 


GPD_SETCTYPE Set the type of the controller to be monitored 
GPD_ASKCTYPE Ask the type of the controller being monitored 
GPD_SETTRIGGER Preset the conditions that will trigger a gameport event 
GPD_ASKTRIGGER _ Inquire the conditions that have been preset for triggering 
GPD_READEVENT Read one or more gameport events from an initialized unit 


GPD_SETCTYPE 


This command establishes the type of controller that is to be connected to the specific gameport 
device. You must have already successfully opened that specific unit before you will be able to 
tell it what type of controller is connected. As of this writing, there are three different legal 
controller types: mouse, absolute joystick, relative joystick, and “no controller.” 
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A mouse controller can report input events for one, two, or three buttons and for positive or 
negative (x,y) movements. A trackball controller or driving controller for various games is gen- 
erally of the same type, and can be declared as a mouse controller. 


An absolute joystick is one that reports one single event for each change in its current location. 
If, for example, the joystick is centered and a user pushes the stick forward, a forward-switch 
event will be generated. A relative joystick, on the other hand, is comparable to an absolute 
joystick with “‘autorepeat’’ installed. As long as the user holds the stick in a position other 
than centered, the gameport device continues to generate position reports. 


As of this writing, there is no direct system software support for proportional joysticks or pro- 
portional controllers. 


You specify the controller type by the following code or its equivalent: 


struct [OStdReq *gamelOMsg; 


setControllerType(type) 
UBYTE *type; 


{ 
/* set type of controller */ 
gamelOMsg->io_Command = GPD_SETCTYPE; 
gamelIOMsg- >io_Data = type; /* show where data can be found */ 
DoIO(gameIOMsg); 
return(0); 


} 


GPD_GETCTYPE 


You use this command to find out what kind of controller has been specified for a particular 
unit. This command puts the controller type into the data area that you specify with the com- 
mand. Here is a sample call: 


SHORT getControllerType(type); 
UBYTE *type; 


{ 
/* get type of controller */ 
gamelOMsg->io_Command = GPD_GETCTYPE; 
gameIOMsg->io_Data = type; /* show where data should be placed */ 
DoIO(gameIOMsg); 
return (gamebuffer(0}); 


} 
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The value that is returned corresponds to one of the four controller types noted in 
GPD_SETCTYPE above. Controller type definitions can be found in the include file named 
devices/gameport.h. 


GPD_SETTRIGGER 


You use this command to specify the conditions that can trigger a gameport event. The device 
won’t reply to your read request until the trigger conditions have been satisfied. 


For a mouse device, you can trigger on a certain minimum-sized move in either the x or y direc- 
tion, on up or down transitions of the mouse buttons, on a timed basis, or any combination of 
these conditions. Here is an example that shows why you might want to use both time and 
movement. Suppose you normally signal mouse events if the mouse moves at least 10 counts in 
either the x or y directions. If you are moving the cursor to keep up with mouse movements 
and the user moves the mouse less than 10 counts, after a period of time you will want to 


update the position of the cursor to exactly match the mouse position. Thus the timed report 
with current mouse counts will be desirable. 


For a joystick device, you can select timed reports as well as button-up and button-down report 
trigger conditions. 


The information needed for gameport trigger setting is placed into a GameTrigger data 
structure: 


struct GamePortTrigger { 


UWORD gpt_Keys; /* key transition triggers */ 

UWORD gpt_Timeout; /* time trigger (vertical blank units) */ 
UWORD gpt_XDelta; /* X distance trigger */ 

UWORD gpt_YDelta; /* Y distance trigger */ 


}3 


The field gpt_Keys can be set to a value of GPTF_UPKEYS to report upward transitions or 
GPTF_DOWNKEYS to report downward transitions. 


The field gpt_Timeout is set to count how many vertical blank units should occur (1/60th of a 


second each) between reports in the absence of another trigger condition. Thus, this specifies 
the maximum report interval. 


Note: If a task sets trigger conditions and does not ask for the position reports (by sending an 
I/O request to be filled in with available reports), the gameport device will queue up several 
additional reports. If the trigger conditions again occur and as many events as the system can 
handle are already queued, the additional triggers will be ignored until the buffer of one or more 
of the existing triggers is read by a device read request. 
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struct GamePortTrigger mousetrigger = { 
GPTF_UPKEYS + GPTF_DOWNKEYS, 
1800, 
XMOVE, 
YMOVE }; 
/* trigger on all mouse key transitions, every 30 seconds, 
* (1800 = 30 times 60 per sec) for any 10 in an x or y direction */ 


You set the trigger by using the following code or the equivalent: 


gamelOMsg->io_Command = GPD_SETTRIGGER; 
/* command to set the trigger conditions */ 
gamelOMsg->i0_Data = &mousetrigger; 
/* show where to find the trigger condition info */ 
DolIO(gameIOMsg); 


Example Programs 


MOUSE PROGRAM 


Here is a complete sample program that lets you open the right gameport device unit and define 
it as a mouse device. You are directed to unplug the mouse and plug it into the right connec- 
tor. Mouse moves and button clicks are reported to the console device that started the pro- 
gram. If you do not move the mouse for 30 seconds, a report is generated automatically. If you 
do not move it for 2 minutes, the program exits. 


[BREA C EEG CAI IAAI I AC TC TTI TR RAIA AA 

* mouse test, for right game port on the Amiga 

* 

* Notes: The right port is used for this test because the input.device task is 
busy continuously with the lefthand port, feeding input events to Intuition or 
* console devices. If Intuition is not activated (applications that take over the 
* whole machine may decide not to activate Intuition) and if no console device is 
* activated, * the input device will never activate, allowing the application free 
* 
* 


* 


rein to use either the left OR the right hand joystick /mouse port. If either 
Intuition or the console device is activated, the lefthand port will yield, at 


* best, every alternate input event to an external application such as this test program. 
* 


* This will undoubtedly mess up either of the two applications and should, 
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therefore, be avoided. It was ok to use the right port in this case, because 
the system has no particular interest in monitoring it. 


Using a function called SetMPort(), you can reconfigure so that the 
mouse is expected in the other port, but that isn’t demonstrated here. 
Jo SSS SS dddaaaaiioiiinioiccai ici ioiinigioiiakaiciaiaiiioai tia ak nk okak ak ar ak rar kai. ak / 


* 
* 
2k 
* 
*x 


#include <exec/types.h > 
#include <exec/devices.h > 
#include <graphics/gfx.h> 
#include <devices/gameport.h> 
#include <devices/inputevent.h > 


LONG GfxBase=0; 


#define XMOVE 10 
#define YMOVE 10 
#define MAX(m,n) (m > n? m:n) 


/* trigger on all mouse key transitions, and every 
* 30 seconds, and for any 10 in an x or y direction */ 


struct GamePortTrigger mousetrigger = { 
GPTF_UPKEYS + GPTF_DOWNKEYS, 
1800, 
XMOVE, 
YMOVE }; 


struct InputEvent *game_data; /* pointer into the returned data area 
* where input event has been sent */ 


SHORT error; 


struct IOStdReq *game_io_msg; 


BYTE gamebuffer|sizeof( struct InputEvent )|; 
BYTE xeamedata; 
SHORT testval: 


struct MsgPort *game_msg_port; 


SHORT movesize; 
extern struct MsgPort *CreatePort(); 
extern struct [OStdReq *CreateStdIO(); 
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SHORT codeval, timeouts; 


#-define IF_NOT_IDLE_TWO_MINUTES while(timeouts < 4) 


main() 


{ 


GfxBase = OpenLibrary(” graphics. library”, 0); 

if (GfxBase == NULL) 

{ 
printf(” Unable to open graphics library\n” ); 
exit(1000); 

} 

printf(” Mouseport Demo\n”); 

printf(” \nMove Mouse from Left Port to Right Port\n”); 

printf(”\nThen move the mouse and click its buttons”); 


timeouts = 0; 


gamedata = &gamebuffer(0}; 
/* point to first location in game buffer */ 


game_msg_port — CreatePort(0,0); 
/* provide a port for the IO response */ 
if(game_msg_port == 0) 


printf(”\nError While Performing CreatePort” ); 
exit(-1); 


j 


game_io_msg = CreateStdIO(game_msg_port); 
/* make an io request block for communicating with 


the keyboard */ 
if(game_io_msg == 0) 
printf(”\nError While Performing CreateStdIO” ); 
DeletePort(game_msg_port); 


exit(-2); 


} 


error = OpenDevice(” gameport.device” ,1,game_io_msg,0); 
/* open the device for access, unit 1 is right port */ 


if(error != 0) 
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printf(”\nError while opening the device, exiting” ); 
DeleteStdIO(game_io_msg); 
DeletePort(game_msg_port); 

exit(-3); 


} 


game_io_msg->io_Length = sizeof(struct InputEvent); 
/* read one event each time we go back to the gameport */ 


game_io_msg->io_Data = (APTR)gamebuffer; 
/* show where to put the data when read */ 


game_data = (struct InputEvent *)gamebuffer; 


/* test the mouse in this loop */ 
set_controller_ty pe(GPCT_MOUSE),; 


/* specify the trigger conditions */ 

game_lo_msg- >1i0_Command = GPD_SETTRIGGER; 
/* show where to find the trigger condition info */ 
game_io_msg->io_Data = (APTR)&mousetrigger; 


/* this command doesn’t wait... returns immediately */ 
SendIO(game_io_msg); 

WaitPort(game_msg_port); 

GetMsg(game_msg_port); 


printf(” \nI will report:”); 

printf(”?\n | Mouse X or Y moves if either is over 10 counts” ); 
printf(”\n Button presses (along with mouse moves if any)” ); 
printf(”\n Or every 30 seconds (along with mouse moves if any)” ); 
printf(” \n if neither move or click happens\n”); 

printf(” \nIf no activity for 2 minutes, the program exits\n”); 


/* from now on, just read input events into the input buffer, one at a 
*time. read-event waits for the preset conditions */ 


game_io_msg->1io_Command = GPD_READEVENT; 
game_io_msg- >io_Data = (APTR)gamebuffer; 


IF_NOT_IDLE_TWO_MINUTES 
{ 


game_io_msg->io_Length = sizeof(struct InputEvent); 
/* read one event each time we go back to the gameport */ 
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printf(”\n Waiting For Mouse Report\n”); 
SendIO(game_io_msg); 


WaitPort(game_msg_port); 
/* this is NOT a busy wait... it is a task-sleep */ 


GetMsg(game_msg_port); 


codeval = game_data->1e_Code; 
switch(codeval) 


case IECODE_LBUTTON: 
printf(” \nMouse Left Button Pressed” ); 
may be_mouse_moved(); 


break; 


case IECODE_RBUTTON: 
printf(” \nMouse Right Button Pressed” ); 
may be_mouse_moved(); 


break; 


case (IECODE_LBUTTON + IECODE_UP_PREFIX): 
printf(” \nMouse Left Button Released” ); 
may be_mouse_moved(); 
break; 


case IECODE_RBUTTON + IECODE_UP_PREFIX): 
printf(” \nMouse Right Button Released” ); 
may be_mouse_moved(); 
break; 


case IECODE_NOBUTTON: 
timeouts++; /* after 2 minutes, dump program if 
* user loses interest */ 
movesize = maybe_mouse_moved(); 
if(movesize == 0) 
{ 


printf(” \n30 seconds passed, no trigger events” ); 


else if(movesize < XMOVE && movesize < YMOVE ) 
{ 


printf(” \n(Even though less than trigger count,” ); 
printf(”\n reporting mouse move at the selected” ); 
printf(” \n timing interval for user info)” ); 
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} 
break; 


default: 
break; 
} 


} 


set_controller_ty pe(GPCT_NOCONTROLLER); 


CloseDevice(game_io_msg); 
DeleteStdIlO(game_io_msg); 
DeletePort(game_msg_port); 


printf(” \nExiting program... 2 minutes with no activity sensed\nl> ”); 
return(0); 


/* if mouse didn’t move far enough to trigger a report, then caller 
* will also report that 30 seconds (1800 vblanks) has elapsed 


+ 


int may be_mouse_moved() 


{ 


int xmove, ymove; 
xmove — game_data- >ie_X; 
ymove = game_data->ie_Y; 


if(xmove != 0 || ymove != 0) 


printf(”\nMouse Moved by X-value %ld, Y-value % 1d”, 
xmove, ymove); 
timeouts = 0; 

} 

if(xmove < 0) xmove = -xmove; 

if(ymove < 0) ymove = -ymove; 


return(MAX(xmove,ymove)); 


j 


int set_controller_ty pe(type) 
SHORT type; 


{ 


/* set type of controller to mouse */ 


game_io_msg->10o_Command = GPD_SETCTYPE; 
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keamedata = type; 


/* set it up */ 
/* this command doesn’t wait... returns immediately */ 
SendIO(game_io_msg); 


WaitPort(game_msg_port); 
GetMsg(game_msg_port); 
return(0); 


JOYSTICK PROGRAM 


/* AK 2 2 oe 2 2 2c 2 2 2 2c oe 2k 2c oe 2 2K 2c 2 2c 2 2c 2K 2 2 2 2K 2K oe 2k 2 2 2c ok 2 2 2 ic 2K 2 2 2 2 2K 2 2c oe 2 2c oc 2 kc 2 2c ok 2K 2k 2k ok 2k 2k + / 


* joystick test, for right game port on the Amiga. 


* Notes: The right port is used for this test because the input.device task is 
busy continuously with the lefthand port, feeding input events to Intuition or 
console devices. If Intuition is not activated (applications that take over the 
whole machine may decide not to activate Intuition) and no console device is 
activated either, the input device will never activate, allowing the application 
free rein to use either the left OR the right hand joystick/mouse port. If 
either Intuition or the console device is activated, the lefthand port will 

yield, at best, every alternate input event to an external application such as 
this test program. This will undoubtedly mess up either of the two applications 
and should therefore be avoided. It was ok to use the right port in this case, 
* because the system has no particular interest in monitoring it. 


* * © + *&© © KF KF 


Ae EK 2 ee Ee EE 2 2K 2 2K 2 2 KE 2K 2 2K 2 2 2 2 2K kK KE a Ke 2 2k ef ee ke 2 2K 2K 2 2K 2K 2 2K 2 KE ee 2 2k 2k 2k 2c fe ke ce co 2 2k 2c 2k 2k 2k 2k * / 


#include <exec/types.h > 
#include <exec/devices.h > 
#include <graphics/gfx.h > 
#include <devices/gameport.h> 
#include <devices/inputevent.h> 


LONG GfxBase=—0; 


#define XMOVE 10 

#define YMOVE 10 

#define MAX(m,n) (m > n? m:n) 

#define FOREVER for(;;) 

struct InputEvent *game_data; /* pointer into the returned data area 
* where input event has been sent */ 
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SHORT - error; 
struct IOStdReq *game_io_msg; 


BYTE gamebuffer|sizeof( struct InputEvent )|; 
BYTE kramebuff; 


SHORT _ testval; 
SHORT _ codevalue; 


struct MsgPort *game_msg_port; 


SHORT movesize; 
extern struct MsgPort *CreatePort(); 
extern struct IOStdReq *CreateStdIO(); 


SHORT codeval, timeouts; 


main() 


{ 


int events_reported; 

events_reported = 0; 

printf(” Joystick Demo\n”); 

printf(”\nPlug a Joystick Into Right Port\n”); 
printf(”\nThen move the stick and click its buttons” ); 


/* point to first location in game buffer */ 
gamebuff = &gamebuffer|0]; 


/* SYSTEM DEVICE COMMUNICATIONS SUPPORT SETUP ROUTINES #**«# */ 
/* provide a port for the IO response */ 
game_msg_port — CreatePort(0,0); 
if(game_msg_port == 0) 
printf(”\nError While Performing CreatePort” ); 
exit(-1); 


} 


/* make an io request block for communicating with the gameport */ 
game_io_msg = CreateStdIO(game_msg_port); 


if(game_io_msg == 0) 


printf(”\nError While Performing CreateStdIO” ); 
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DeletePort(game_msg_port); 
exit(-2); 


} 


/* EK 2 2 2k 2c 2k 2k 2c ek 2 2 KE 2 Ko 2 2 2K KK kK kK 2k 2k kK aK OK ak kk kak oko 2 kK KK 2 2k * / 


/* OPEN THE DEVICE */ 


/* open the device for access, unit 1 is right port */ 
error = OpenDevice(” gameport.device” ,1,game_io_msg,0); 


if(error != 0) 

{ 
printf(”\nError while opening the device, exiting” ); 
DeleteStdIO(game_io_msg); 
DeletePort(game_msg_port); 
exit(-3); 

} 


/* 2K 2 Ae 2K 2 fe 2 ac ak 2 2 fe ok 2c oe 2 2 2c oe 2 ae ke 2 2 2 2 2 oc af ofc oo 2 2 2k ke oie ate fe ok a 2 afc ic oe 2 2 ake 2 ofc of ok 2 2k 2k * / 


/* SET THE DEVICE TYPE */ 

game_data = (struct InputEvent *)gamebuffer; 

/* test the joystick in this loop */ 

if (set_controller_type(GPCT_ABSJOYSTICK) != 0) 


printf(”\nError while trying to set GPCT_ABSJOYSTICK”); 
DeleteStdIO(game_io_msg); 
DeletePort(game_msg_port); 
exit(-4); 
} 
[36 BBA O SAGES ISIE AEE ACSIA SAGE IES IIE. / 
/* SET THE DEVICE TRIGGER */ 
if (set_controller_trigger() != 0) 
{ 
printf(”\nError while trying to set controller trigger” ); 
DeleteStdIO(game_io_msg); 
DeletePort(game_msg_port); 
exit(-4); 
} 
[36 ESSE AOS ASSO OSES EASES BE EAI IIA / 


/* TELL USER WHAT YOU WILL BE DOING */ 
printf(” \nI will report: \n”); 


printf(’?\n Stick X or Y moves”); 
printf(”\n | Button presses (along with stick moves if any)” ); 
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/* FOO OIG RIG Ik a kk aK ka a ak ak ak kok ak ak ak + / 


/* SETUP THE IO MESSAGE BLOCK FOR THE ACTUAL DATA READ */ 


/* from now on, just read input events into the input buffer, one at a 
* time; read-event waits for the preset conditions */ 


game_lo_msg->io_Command = GPD_READEVENT; 
game_io_msg->io_Data = (APTR)gamebuffer; 


/* read one event each time we go back to the gameport */ 
game_io_msg->io_Length = sizeof(struct InputEvent); 


/* don’t use quick io */ 
game_io_msg->10_F lags — 0; 


/* AE 2 2 fe fc fe fe 2c ck 2 2K 2 akc oc 2 KK 2K 2K oe KK 2K 2c ic 2c 2h fe 2c of 2c fe fe ke 2c ke 2 2 2 2 ke 2c 2 2K 2 ok a 2c ic ok oc 2K 2k ok + / 


/* LOOP FOREVER +*/ 


FOREVER 

{ 
/* read one event each time we go back to the gameport */ 
game_io_msg->io_Length = sizeof(struct InputEvent); 


printf{(”\n Waiting For Joystick Report\n”); 
SendIO(game_io_msg); 
WaitPort(game_msg_port); 

/* this is NOT a busy wait... it is a task-sleep */ 
GetMsg(game_msg_port); 


codevalue = game_data- > ie_Code; 


if(codevalue == IECODE_LBUTTON) 
printf(” \nFire Button pressed” ); 

if(codevalue =— (IECODE_LBUTTON + IECODE_UP_PREFIX)) 
printf(” \nFire Button released” ); 


which_direction(); 
showbugs(); 
if (events_reported++ >12) break; 


} 
set_controller_ty pe(GPCT_NOCONTROLLER); 


CloseDevice(game_io_msg); 
DeleteStdIO(game_io_msg); 
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} 


DeletePort(game_msg_port):; 


printf(” \nExiting program... 12 events reported.\nl> ”); 
return(0); 


int which_direction() 


} 


SHORT xmove, ymove; 
xmove = game_data->1e_X; 
ymove = game_data->ie_Y; 


switch(ymove) 
{ 
case (-1): 
printf(” \nForward” ); 
break; 
case (1): 
printf(” \nBack”); 
break; 
default: 
break; 
} 


switch(xmove) 

{ 
case (-1): 
printf(” \nLeft” ); 
break; 
case (1): 
printf(”\nRight”); 
break; 

default: 
break; 

} 


return(0); 


int set_controller_ty pe(type) 
SHORT type; 


{ 


game_lo_msg->10_Command = GPD_SETCTYPE; 
/* set type of controller to mouse */ 
game_io_msg->10_Length — 1; 
game_io_msg->io_Data = (APTR)gamebuff; 
*gamebuff = type; 
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SendIO(game_io_msg); 

/* set it up */ 

/* this command doesn’t wait... returns immediately */ 
WaitPort(game_msg_port); 

GetMsg(game_msg_port); 

return((int)game_io_msg- > io_Error); 


} 


int set_controller_trigger() 


{ 


struct GamePortTrigger gpt; 


game_lo_msg->10_Command = GPD_SETTRIGGER; 
game_io_msg->io_Length = sizeof(gpt); 
game_io_msg->io_Data = (APTR)&gpt; 

gpt.gpt_Keys = GPTF_UPKEYS+GPTF_DOWNKEYS; 
gpt.gpt_Timeout = 0; 

gpt.gpt_XDelta = 1; 

gpt.gpt_YDelta — 1; 


return(DolO(game_io_msg)); 


} 


showbugs() 


{ 


struct InputEvent *e; 


e = (struct InputEvent *)&gamebuffer|0]; 

/* where the input event gets placed */ 

printf(” \nie_Class = % |x” ,e- >ie_Class); 

printf(” \nie_SubClass = % Ix” ,e- >ie_SubClass): 
printf(” \nie_Code = %1x”, e- >ie_Code); 

printf(” \nie_Qualifier = %1x” ,e- >ie_Qualifier); 


( 
( 
( 
( 
( 
( 


printf(” \nie_X = %ld”, e- >ie_X); 
printf(” \nie_Y = %ld”, e- >ie_Y); 
printf(” \nie_TimeStamp(seconds) = %1x”, e- >ie_TimeStamp.tv_secs); 


return(0); 
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Chapter 12 


Narrator Device 


This chapter provides routines for accessing both the narrator device and the translator library 
and shows how some of the parameters passed to the device can affect the output. In addition, 
this chapter contains a nontechnical explanation of how to effectively utilize the speech device. 


A more technical explanation is also provided for those who may be interested in how the 
speech is actually produced. 
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Introduction 


Two different subsystems comprise the speech system on the Amiga. They are the narrator dev- 
tce, Which communicates with the audio device to actually produce human-like speech, and the 


translator library, which contains a routine that translates English text into phonemes suitable 
for the narrator device. 


The Translator Library 
The translator library provides a single routine, named Translate(), that converts an English 
language string into a phonetic string. To use this function, you must first open the library. 


Setting a global variable, TranslatorBase, to the value returned from the call to 
OpenLibrary() enables the Amiga linker to correctly locate the translator library: 


struct Library *TranslatorBase; 


TranslatorBase = OpenLibrary(”translator.library” ,RREVISION); 
if(TranslatorBase === NULL) exit (CANT_OPEN_TRANSLATOR); 


Note that for the OpenLibrary() call to succeed, the directory currently assigned by Amiga- 
DOS as LIBS: must contain translator.library. 


USING THE TRANSLATE FUNCTION 


Once the library is open, you can call the translate function: 


UBYTE *sampleinput; /* pointer to sample input string */ 
UBYTE outputstring[500];| _/* place to put the translation */ 
SHORT rtnCode; /* return code from function */ 
sampleinput — ”this is a test’; /* a test string of 14 characters */ 


rtnCode = Translate(sampleinput,14,outputstring,500); 


The input string will be translated into its phoneme equivalent and can be used to feed the nar- 
rator device. If you receive a nonzero return code, you haven’t provided enough output buffer 
space to hold the entire translation. In this case, the Translate() function breaks the transla- 
tion at the end of a word in the input stream and returns the position in the input stream at 
which the translation ended. You can use the output buffer, then call the Translate() function 
again, starting at this original ending position, to continue the translation where you left off. 
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Note, however, that the value returned is negative. Therefore, you must use -rtnCode as the 
starting point for a new translation. 


ADDITIONAL NOTES ABOUT TRANSLATE 


The English language has many words that do not sound the same as they are spelled. The 
translator library has an exception table that it consults as the translation progresses. Words 
that are not in the exception table are translated literally. Therefore, it is possible that certain 
words will not translate well. You can improve the quality of the translation by handling those 
words on your own, using the tutorial information included at the end of this chapter. 

As with all other libraries of routines, if you have opened the translator library for use, be sure 


to close it before your program exits. If the system needs memory resources, it can then expel 
closed libraries to gain additional space. 


The Narrator Device 


The narrator device on the Amiga provides two basic functions: 


o You can write to the device and ask it to speak a phoneme-encoded string in a specific 
manner— pitch, male/female, various speaking rates, and so on. 


o You can read from the device. As it speaks, the device can generate mouth shapes for 
you and you can use the shapes to perform a graphics rendering of a face and mouth. 


OPENING THE NARRATOR DEVICE 


To use the narrator device, you must first open the device. The narrator device is disk-resident. 
For the OpenDevice() call to succeed, the narrator device must be present in the directory 
currently assigned by AmigaDOS to the DEVS: directory. 


To communicate with the narrator device, like any other device, you must pass an IORequest 
block to OpenDevice(). The block used by the narrator device for a write is a special format 
called a narrator_rb. The block used for a read is also a special format, called a mouth_rb. 
Both blocks are described in the sections that follow. A sample OpenDevice() sequence for the 
narrator device follows. Notice that two request blocks are created, one for writing to the dev- 
ice and one for reading from it. For brevity, the error checking is left out of this short example. 
It is, however, utilized in the sample program later on. 
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struct narrator_rb *writeNarrator; 

struct narrator_rb *read Narrator; 

writeport = CreatePort(0,0); 

readport = CreatePort(0,0); 

writeNarrator = (struct narrator_rb *)CreateExtIlO(writeport, 
sizeof(struct narrator_rb)); 

readNarrator = (struct mouth_rb *)CreateExtIO(readport, 
sizeof(struct mouth_rb)); 


The routine CreateExtIO() is in the “Other Routines” appendix of the Amiga ROM Kernel 


Reference Manual: Exec. CreatePort() is contained in amiga.lib and can be accessed by link- 
ing your program to amiga.lib. 


CONTENTS OF THE WRITE REQUEST BLOCK 


You can control several characteristics of the speech, as indicated in the narrator request block 
structure shown below. 


struct narrator_rb { 


struct IOStdReq message; /* Standard IORB */ 


UWORD rate; /* Speaking rate (words/minute) */ 
UWORD pitch; /* Baseline pitch in Hertz */ 
UWORD mode; /* Pitch mode */ 
UWORD $s sex; /* Sex of voice */ 
UBYTE *ch_masks; /* Pointer to audio alloc maps */ 
UWORD nm_masks; /* Number of audio alloc maps */ 
UWORD volume; /* Volume. 0 (off) thru 64 */ 
UWORD sampfregq; /* Audio sampling freq */ 
UBYTE mouths; /* If non-zero, generate mouths */ 
UBYTE chanmask; /* Which ch mask used (internal)* / 
UBYTE numchan; /* Num ch masks used (internal) */ 
UBYTE pad; /* For alignment */ 
i3 
where 
rate 
is the speed in words per minute that you wish it to speak. 
pitch 


is the baseline pitch. If you are using an expressive voice rather than a monotone, the 
pitch will vary above and below this baseline pitch. 
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mode 


determines whether you have a monotone or expressive voice. 


sex 


determines if the voice is male or female. 


ch_masks, nm_masks, volume, sampfreq 
are described in the chapter called ‘‘Audio Device.”’ 


mouths 


is set to nonzero before starting a write if you want to read mouths using the read com- 
mand while the system is speaking. 


chanmask, numchan, pad 
are for system use only. 


The system default values are shown in the files devices/narrator.h and devices/narrator.t. 
When you call OpenDevice(), the system initializes the request block to the default values. If 
you want other than the defaults, you must change them after the device is open. 


CONTENTS OF THE READ REQUEST 


The mouth_rb data structure follows. Notice that it is an extended form of the narrator_rb 
structure. 


struct mouth_rb { 
struct narrator_rb voice; /* Speech IORB */ 


UBYTE width; /* Width (returned value) */ 
UBYTE height; /* Height (returned value) */ 
UBYTE shape; /* Internal use, do not modify */ 
UBYTE pad; /* For alignment */ 


3 


The fields width and height will, on completion of a read-request, contain an integer value pro- 
portional to the mouth width and height that are appropriate to the phoneme currently being 
spoken. When you send a read request, the system does not return a response until one of two 
things happens. Either a different mouth size is available (this prevents you from drawing and 
redrawing the same shape or having to check whether or not it is the same) or the speaking has 
completed. You must check the error return field when the read request block is returned to 
determine if the request block contains a new mouth shape or simply is returning status of 
ND_NoWrite (no write in progress, all speech ended for this request). 
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OPENING THE NARRATOR DEVICE 


This section demonstrates opening the device as well as synchronizing a read request so that it 
responds only to the write request for which the device is opened. You can read the mouth 
shapes only if the write request contains the same unit number and a write is currently in pro- 
gress; the system returns an error if the numbers don’t match or if the write has completed. 
Note again that error checking is deferred to the example program at the end of the chapter. 


SHORT openError; 


openError = OpenDevice(”narrator.device” ,0,writeNarrator,0); 
/* after error checking, synchronize the read and write requests * / 
read Narrator- >narrator_rb.message.io_Device = 


writeNarrator- >message.io_Device; /* copy device info */ 
read Narrator- >narrator_rb.message.io_Unit = 
writeNarrator- >message.io_Unit; /* copy unit info */ 


At this point, it is acceptable to change the default values before issuing a write. 


More details about what OpenDevice() performs are contained in the narrator device summary 
pages. 


PERFORMING A WRITE AND A READ 


You normally perform a write command by using the functions BeginIO() or SendIO() to 
transmit the request block to the narrator device. This allows the narrator’s task to begin the 
I/O, while your task is free to do something else. The something else may be issuing a series of 
read commands to the device to determine mouth shapes and drawing them on-screen. The fol- 
lowing sample set of function calls implements both the write and read commands in a single 
loop. Again, error checking is deferred to the sample program. 
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SHORT readError; 


writeNarrator- > message.io_Length = strlen(outputstring); 

/* tell it how many characters the translate function returned * / 
writeNarrator- > message.io_Data = outputstring; 

/* tell it where to find the string to speak */ 
SendIO(writeNarrator); 

/* return immediately, run tasks concurrently */ 


read Narrator- >voice.message.io_Error = 0; 
while((readError = readNarrator->voice.message.io_Error) != 


ND_NoWrite) 
{ 


DoIO(readNarrator); 
/* put task to sleep waiting for a different mouth shape or 
* return of the message block with the error field showing 
* no write in progress 
*/ 
DrawMouth(readNarrator- > width,read Narrator- > height); 
/* user’s own unique routine, not provided here */ 
} 
GetMsg(writeport); /* remove the write message from the 
* writeport so that it can be reused */ 


The loop continues to send read requests to the narrator device until the speech output has 
ended. DoIO() automatically removes the read request block from the readport for reuse. 


SendIO() is used to transmit the write request. When it completes, the write request will be 
appended to the writeport, and must be removed before it can be reused. 


Sample Program 


The following sample program uses the system default values returned from the OpenDevice() 
call. It translates and speaks a single phrase. 
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# include ”exec/types.h” 
#include ” exec/exec.h” 


#include ”exec/nodes.h” 
#include ”exec/lists.h” 
#include ”exec/memory.h” 
#include ”exec/interrupts.h” 
#include ”exec/ports.h” 
#include ”exec/libraries.h” 
#include ”exec/io.h” 
#include ”exec/tasks.h” 
#include ” exec/execbase.h” 


#include ” devices /narrator.h” 
#include ” libraries/translator.h” 


struct MsgPort *readport—0; 
struct MsgPort *writeport—0; 


extern struct MsgPort *CreatePort(); 
extern struct I[ORequest *CreateExtIO(); 


struct narrator_rb *writeNarrator=—0; 
struct mouth_rb *read Narrator—0; 
struct Library *TranslatorBase—0; 


UBYTE *sampleinput; /* pointer to sample input string */ 
UBYTE outputstring|[500]; /* place to put the translation */ 
SHORT rtnCode; /* return code from function */ 


SHORT readError; 

SHORT writeError; 

SHORT error; 

BYTE audChanMasks|/4] = { 3,5,10,12 };  /* which channels to use */ 


#define CANT_OPEN_TRANSLATOR -100 
#define CANT_OPEN_NARRATOR -200 
#define CREATE _PORT_PROBLEMS -300 
#define CREATE_IO_ PROBLEMS -400 
#define CANT_PERFORM_WRITE -500 
#define REVISION 1 


extern struct Library *OpenLibrary(); 
main() 


{ 
TranslatorBase = OpenLibrary(” translator.library” ,REVISION); 
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if(TranslatorBase === NULL) exit (CANT_OPEN_TRANSLATOR); 
sampleinput = ”this is a test”; /* a test string of 14 characters */ 
rtnCode = Translate(sampleinput,14,outputstring,500); 

error = rtnCode + 100; 

if(rtnCode != 0) goto cleanup0; 


writeport = CreatePort(0,0); 
if(writeport == NULL) { error=CREATE_PORT_PROBLEMS; goto cleanup]; } 
readport = CreatePort(0,0); 
if(readport === NULL) { error=CREATE_PORT_PROBLEMS:; goto cleanup2; } 
writeNarrator = (struct narrator_rb *)CreateExtlO(writeport, 

sizeof(struct narrator_rb)); 
if(writeNarrator === NULL) { error—=CREATE_IO_PROBLEMS; goto cleanup3; } 
readNarrator = (struct mouth_rb *)CreateExtIO(readport, 

sizeof(struct mouth_rb)); 


if(readNarrator === NULL) { error—=CREATE_IO_PROBLEMS; goto cleanup4; } 
/* SET UP PARAMETERS FOR WRITE-MESSAGE TO THE NARRATOR DEVICE */ 


/* show where to find the channel masks */ 
writeNarrator- >ch_masks = (audChanMasks); 


/* and tell it how many of them there are */ 
writeNarrator- >nm_masks = sizeof(audChanMasks); 


/* tell it where to find the string to speak */ 
writeNarrator- > message.io_Data = (APTR)outputstring; 


/* tell it how many characters the translate function returned */ 
writeNarrator- > message.io_Length = strlen(outputstring); 


/* if nonzero, asks that mouths be calculated during speech */ 
writeNarrator- > mouths = 1; 


/* tell it this is a write-command */ 
writeNarrator- > message.io_Command = CMD_WRITE; 


/* Open the device */ 


error = OpenDevice(” narrator.device”, 0, writeNarrator, 0); 
if(error !== 0) goto cleanup4; 


/* SET UP PARAMETERS FOR READ-MESSAGE TO THE NARRATOR DEVICE */ 


/* tell narrator for whose speech a mouth is to be generated */ 
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read Narrator- > voice.message.io_Device = 
writeNarrator- > message.io_Device; 

read Narrator- > voice.message.io_Unit = 
writeNarrator- > message.io_Unit; 


read Narrator-> width = 0; 
readNarrator- >height = 0; /* initial mouth parameters */ 


read Narrator- > voice.message.io_Command = CMD_READ; 
/* initial error value */ 
read Narrator- > voice.message.io_Error = 0; 


/* Send an asynchronous write request to the device */ 


writeError = SendJO(writeNarrator); 
if(writeError !== NULL) { error—=CANT_PERFORM_WRITE; goto cleanup5; } 


/* return immediately, run tasks concurrently */ 
/* keep sending reads until it comes back saying ”no write in progress” */ 


while((readError = read Narrator- >voice.message.io_Error) != 


ND_NoWrite) 
{ 


DolO(read Narrator); 

/* put task to sleep waiting for a different mouth shape 

* or return of the message block with the error field 

* showing no write in progress 

=) 

DrawMouth(read Narrator- > width,read Narrator- > height); 
/* user’s own unique routine, not provided here */ 


} 


Delay(30); 


rtnCode = Translate(” No it is not” ,13,outputstring,500); 

writeNarrator- >sex = FEMALE; 

writeNarrator- > pitch = MAXPITCH; /* raise pitch from default value */ 
writeNarrator- >message.io_Data = (APTR)outputstring; 
writeNarrator- > message.io_Length = strlen(outputstring); 
DolO(writeNarrator); 


Delay(30); 


rtnCode = Translate(” Please! I am speaking now!” ,26,outputstring,500); 
writeNarrator- >sex = MALE; 
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writeNarrator- > pitch = DEFPITCH; 

writeNarrator- > message.io_Data = (APTR)outputstring; 
writeNarrator- > message.io_Length = strlen(outputstring); 
DolO(writeNarrator); 


Delay(30); 


rtnCode = Translate( 
” Well, you are not very interesting, sol am going home!”, 
55,outputstring,500); 
writeNarrator- >sex = FEMALE; 
writeNarrator- > pitch = MAXPITCH; 
writeNarrator- > message.io_Data = (APTR)outputstring; 
writeNarrator- >message.io_Length = strlen(outputstring); 
DolO(writeNarrator); 


Delay(30); 


rtnCode = Translate(” Bye Bye” ,7,outputstring,500); 
writeNarrator- >sex = MALE; 

writeNarrator- > pitch = DEFPITCH; 
writeNarrator->rate = 7; /* slow him down */ 
writeNarrator- > message.io_ Data = (APTR)outputstring; 
writeNarrator- > message.io_Length = strlen(outputstring); 
DolO(writeNarrator); 


cleanupd: 
if(writeNarrator != 0) 
CloseDevice(writeNarrator); 
/* terminate access to the device */ 


/* now return system memory to the memory allocator */ 


cleanup4: 
if(readNarrator != 0) 
DeleteExtIO(read Narrator,sizeof(struct mouth_rb)); 
cleanups: 
if(write Narrator != 0) 
DeleteExtIO(writeNarrator,sizeof(struct narrator_rb)); 


cleanup2: 
if(readport != 0) 
DeletePort(read port); 
cleanupl: 


if(writeport != 0) 
DeletePort(writeport); 


Narrator Device 371 


cleanup0O: 
if(TranslatorBase != 0) 
CloseLibrary(TranslatorBase); 
/* terminate access to the library */ 


if(error != 0) exit(error); 
\ /* end of test */ 


DrawMouth(w,h) 
SHORT w,h; 
f return(0); /* dummy routine */ } 


int strlen(string) 
char *string; 
{ 
int i,length; 
length = -1; 
for(i=0; i<256; i++) /* 256 characters max length at this time */ 
{ 
if(*string++ —=—’ ’) { length = i+1; break; }; 


} 


return(length); 


The loop continues to send read requests to the narrator device until the write request has com- 
pleted. Then the program cleans up and exits. 


You can experiment with the narrator device by using values other than the default, changing 
them before the write command is sent to the device. 


How to Write Phonetically for Narrator 


This section describes in detail the procedure used to specify phonetic strings to the Narrator 
speech synthesizer. No previous experience with phonetics is required. The only thing you may 
need is a good pronouncing dictionary for those times when you doubt your own ears. You do 
not have to learn a foreign language or computer language. You are just going to learn how to 
write down the English that comes out of your own mouth. In writing phonetically you do not 
have to know how a word is spelled, just how it is said. 


Narrator works on utterances at the sentence level. Even if you want to say only one word, 


Narrator will treat it as a complete sentence. ‘Therefore, Narrator wants one of two punctua- 
tion marks to appear at the end of every sentence —a period (.) or a question mark (°). If no 
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punctuation appears at the end of a string, Narrator will append a period to it. The period is 
used for almost all utterances and will cause a final fall in pitch to occur at the end of a sen- 
tence. The question mark is used at the end of yes/no questions only, and results in a final rise 
in pitch. For example, the question, Do you enjoy using your Amiga? would take a question 
mark at the end because the answer to the question is either yes or no. The question, What ts 
your favorite color? would not take a question mark and should be followed by a period. Narra- 
tor recognizes other punctuation marks as well, but these are left for later discussion. 


PHONETIC SPELLING 


Utterances are usually written phonetically using an alphabet of symbols known as I.P.A. (for 
“International Phonetic Alphabet”). This alphabet is found at the front of most good dic- 
tionaries. The symbols can be hard to learn and are not available on computer keyboards, so 
the Advanced Research Projects Agency (ARPA) came up with Arpabet, a way of representing 
each symbol using one or two upper-case letters. Narrator uses an expanded version of Arpabet 
to specify phonetic sounds. 


A phonetic sound, or phoneme, is a basic speech sound, almost a speech atom. Working back- 
wards, sentences can be broken into words, words into syllables, and syllables into phonemes. 
The word cat has three letters and (coincidentally) three phonemes. Looking at the table of 
phonemes we find the three sounds that make up the word cat. They are K, AE, and T, writ- 
ten as KAET. The word cent translates as S, EH, N and T, or SEHNT. Notice that both 
words begin with a c but because the c says k in cat we use the phoneme K. In cent the c says 
sso we use the phoneme S. You may also have noticed that there is no C phoneme. 


The above example illustrates that a word rarely sounds like it looks in English spelling. These 
examples introduce you to a very important concept: spell it like it sounds, not like it looks. 


CHOOSING THE RIGHT VOWEL 


Phonemes, like letters, are divided into the two categories of vowels and consonants. Loosely 
defined, a vowel is a continuous sound made with the vocal cords vibrating and air exiting the 
mouth (as opposed to the nose). All vowels use a two-letter code. A consonant is any other 
sound, such as those made by rushing air (like S or TH), or by interruptions in air flow by the 
lips or tongue (like B or T). Consonants use a one- or two-letter code. 


In English we write with only five vowels: a, e, i, o and u. It would be easy if we only sazd five 
vowels. Unfortunately, we say more than 15 vowels. Narrator provides for most of them. You 
choose the proper vowel by listening. Say the word out loud, perhaps extending the vowel 
sound you want to hear. Compare the sound you are making to the sounds made by the vowels 
in the example words to the right of the phoneme list. For example, the a in apple sounds the 
same as the a in cat, not like the as in Amiga, talk, or made. Notice also that some of the 
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example words in the list do not even use any of the same letters contained in the phoneme 
code; for example, AA as in hot. 


Vowels are divided into two groups: those that maintain the same sound throughout their 
durations and those that change their sound. The ones that change are called diphthongs. 
Some of us were taught the terms long and short to describe vowel sounds. Diphthongs fall into 
the long category, but these two terms are inadequate to fully differentiate between vowels and 
should be avoided. The diphthongs are the last six vowels listed in the table. Say the word 
made out loud very slowly. Notice how the a starts out like the e in bet but ends up like the e 
in beet. The a therefore is a diphthong in this word and we would use EY to represent it. 
Some speech synthesis systems require you to specify the changing sounds in diphthongs as 
separate elements, but Narrator takes care of the assembly of diphthongal sounds for you. 


CHOOSING THE RIGHT CONSONANT 


Consonants are divided into many categories by phoneticians, but we need not concern our- 
selves with most of them. Picking the correct consonant is very easy if you pay attention to 
just two categories: voiced and unvoiced. A voiced consonant is made with the vocal cords 
vibrating, and an unvoiced one is made when the vocal cords are silent. Sometimes English uses 
the same letter combinations to represent both. Compare the th in thin and in then. Notice that 
the first is made with air rushing between the tongue and upper teeth. In the second, the vocal 
cords are vibrating also. The voiced th phoneme is DH, the unvoiced is TH. Therefore, thin is 
spelled TH, IH, N or THIHN, and then is spelled DH, EH, N or DHEHN. A sound that is par- 
ticularly subject to mistakes is voiced and unvoiced s spelled Zor S. To put it clearly, bats 
ends in S, suds ends in Z. What kind of s does closet have? How about close? Say all of these 
words out loud to find out. Actually close changes its meaning when the s is voiced or unvoiced: 
I love to be close to you. versus Whai tame do you close? 


Another sound that causes some confusion is the r sound. ‘There are two different r-like 
phonemes in the Narrator alphabet: R under the consonants and ER under the vowels. Which 
one do you use? Use ER if the r sound is the vowel sound in the syllable. Words that take ER 
are absurd, computer and flirt. Use R if the r sound precedes or follows another vowel sound in 


that syllable, such as in car, write, or craft. Rooster uses both kinds of r. Can you tell which is 
which? 


CONTRACTIONS AND SPECIAL SYMBOLS 


There are several phoneme combinations that appear very often in English words. Some of 
these are caused by our laziness in pronunciation. Take the word connector for example. The o 
in the first syllable is almost swallowed out of existence. You would not use the AA phoneme; 
you would use the AX instead. It is because of this relaxation of vowels that we find ourselves 
using AX and IX very often. Since this relaxation frequently occurs before 1, m and n, Narrator 
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has a shortcut for typing these combinations. Instead of personal being spelled PERSIXNAXL, 
we can spell it PERSINUL, making it a little more readable. Anomaly goes from AXNAAMAX- 
LIY to UNAAMULIY, and KAAMBIXNEYSHIXN becomes KAAMBINEYSHIN for combina- 
tion. It may be hard to decide whether to use the AX or IX brand of relaxed vowel. The only 
way to find out is to try both and see which sounds best. 


Other special symbols are used internally by Narrator. Sometimes they are inserted into or sub- 
stituted for part of your input sentence. You can type them in directly if you wish. The most 
useful is probably the Q or glottal stop; an interruption of air flow in the glottis. The word 
Atlantic has one between the t and the /. Narrator knows there should be a glottal stop there 
and saves you the trouble of typing it. But Narrator is only close to perfect, so sometimes a 
word or word pair might slip by that would have sounded better with a Q stuck in someplace. 


STRESS AND INTONATION 


It is not enough to tell Narrator what you want said. For the best results you must also tell 
Narrator how you want it said. In this way you can alter a sentence’s meaning, stress impor- 
tant words, and specify the proper accents in polysyllabic words. These things improve the 
naturalness and thus the intelligibility of Narrator’s spoken output. 


Stress and intonation are specified by the single digits 1-9 following a vowel phoneme code. 
Stress and intonation are two different things but are specified by a single number. Stress is, 
among other things, the elongation of a syllable. Because a syllable is either stressed or not, the 
presence of a number after the vowel in a syllable indicates stress on that syllable. The value of 
the number indicates the intonation. From this point onward, these numbers will be referred to 
as stress marks. Intonation here means the pitch pattern or contour of an utterance. The 
higher the stress mark, the higher the potential for an accent in pitch (a rise and fall). A 
sentence’s basic contour is comprised of a quickly rising pitch gesture up to the first stressed 
syllable in the sentence, followed by a slowly declining tone throughout the sentence, and finally 
a quick fall to a low pitch on the last syllable. The presence of additional stressed syllables 
causes the pitch to break its slow, declining pattern with rises and falls around each stressed 
syllable. Narrator uses a very sophisticated procedure to generate natural pitch contours based 
on how you mark the stressed syllables. 


HOW AND WHERE TO PUT THE STRESS MARKS 


The stress marks go immediately to the right of vowel phoneme codes. The word cat has its 
stress marked after the AE so we get KAE5T or KAE9T. You generally have no choice about 
the location of a number; there is definitely a right and wrong location. Either a number should 
go after a vowel or it should not. Narrator will not flag an error if you forget to put a stress 
mark in or if you place one on the wrong vowel. It will only tell you if a stress mark is in the 
wrong place, such as after a consonant. 
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The rules for placing stress marks are as follows: 


Always place a stress mark in a content word. A content word is one that contains 
some meaning. Nouns, verbs, and adjectives are all content words. Boat, huge, tonsils 
and hypertensive are all content words; they tell the listener what you are talking 
about. Words like but, the, if and is are not content words. They do not convey any 
real-world meaning at all but are required to make the sentence function. Thus, they 
are given the name function words. 


Always place a stress mark on the accented syllable(s) of polysyllabic words, whether 
they are content or function words. A polysyllabic word is any word of more than one 
syllable. Commodore has its stress (or accent as it is often called) on the first syllable 
and would be spelled KAASMAXDOHR. Computer is stressed on the second syllable, 
producing KUMPYUW5STER. 


If you are in doubt about which syllable gets the stress, look the word up in a diction- 
ary and you will find an accent mark over the stressed syllable. If more than one syll- 
able in a word receives stress, they usually are not of equal value. These are referred to 
as primary and secondary stresses. The word understand has its first and last syllables 
stressed, with stand getting primary stress and wun secondary, which produces 
AHINDERSTAEAND. Syllables with secondary stress should be marked with a value 
of only 1 or 2. 


Compound words (words with more than one root) such as base/ball, soft/ware, 
lunch/wagon, and house/boat can be written as one word but should be thought of as 
separate words when marking stress. Thus, lunchwagon would be spelled 
LAH5NCHWAE2GIN. Notice that lunch got a higher stress mark than wagon. This is 
common in compound words; the first word usually receives the primary stress. 


WHAT STRESS VALUE DO I USE? 


If you get the spelling and stress mark positions correct, you are 95 percent of the way to a 
good sounding sentence. The next thing to do is decide on the stress mark values. They can be 
roughly related to parts of speech, and you can use table 12-1 as a guide to assigning values. 
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Table 12-1: Recommended Stress Values 


Part of Speech Stress Value 


Nouns 
Pronouns 
Verbs 
Adjectives 
Adverbs 
Quantifiers 
Exclamations 
Articles 
Prepositions 


(no stress) 


Conjunctions 
Secondary stress 


—- OOWodDAda NIN ot Rh W Ol 


(sometimes 2) 


The above values merely suggest a range. If you want attention directed to a certain word, 
raise its value. If you want to downplay a word, lower it. Sometimes even a function word can 
be the focus of a sentence. It is quite conceivable that the word “to” in the sentence “Please 
deliver this to Mr. Smith.” could receive a stress mark of 9. This would add focus to the word 
“to” indicating that the item should be delivered to Mr. Smith in person. 


PUNCTUATION 


In addition to the period or question mark that is required at the end of a sentence, Narrator 
recognizes several other punctuation marks: dashes, commas, and parentheses. The comma goes 
where you would normally put a comma in an English sentence. It causes Narrator to pause 
with a slightly rising pitch, indicating that there is more to come. The use of additional 
commas—that is, more than would be required for written English—is often helpful. They 
serve to set clauses off from one another. There is a tendency for a listener to lose track of the 
meaning of a sentence if the words run together. Read your sentence aloud while pretending to 
be a newscaster. The locations for additional commas should leap out at you. 


The dash serves almost the same purpose as the comma, except that the dash does not cause 
the pitch to rise so severely. A rule of thumb is: Use dashes to divide phrases, commas to 
divide clauses. For a definition of these terms, consult a high school English book. 


Parentheses provide additional information to Narrator’s intonation routine. They should be 
put around noun phrases of two or more content words. This means that the noun phrase, “a 
giant yacht” should be surrounded with parentheses because it contains two content words, 
giant and yacht. The phrase my friend should not have parentheses around it because it con- 
tains only one content word. Noun phrases can get pretty big, like “the silliest guy I ever saw”’ 
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or ‘‘a big basket of fruit and nuts.” The parentheses really are most effective around these large 
phrases; the smaller ones can sometimes go without. The effect of parentheses is subtle, and in 
some sentences you might not even notice their presence. In sentences of great length, however, 
they help provide for a very natural contour. 


HINTS FOR INTELLIGIBILITY 


There are a few tricks you can use to improve the intelligibility of a sentence. Often, a polysyl- 
labic word is more recognizable than a monosyllabic word. For instance, instead of saying huge, 
say enormous. The longer version contains information in every syllable, thus giving the 
listener three times the chance to hear it correctly. This can be taken to extremes, so try not to 
say things like “This program has a plethora of insects in it.” 


Another good practice is to keep sentences to an optimal length. Writing for reading and writ- 
ing for speaking are two different things. Try not to write a sentence that cannot be easily spo- 
ken in one breath. Such a sentence tends to give the impression that the speaker has an infinite 
lung capacity. Try to keep sentences confined to one main idea. A run-on sentence tends to 
lose its meaning after a while. 


New terms should be highly stressed the first time they are heard. If you are doing a tutorial or 
something similar, stress a new term at its first occurrence. All subsequent occurrences of that 
term need not be stressed as highly because it is now ‘‘old news.” 


The above techniques are but a few ways to enhance the performance of Narrator. You will 
probably find some of your own. Have fun. | 


EXAMPLE OF ENGLISH AND PHONETIC TEXTS 


Cardiomyopathy. I had never heard of it before, but there it was listed as the form of heart 
disease that felled not one or two but all three of the artificial heart recipients. A little research 
produced some interesting results. According to an article in the Nov. 8, 1984, New England 
Journal of Medicine, cigarette smoking causes this lethal disease that weakens the heart’s pump- 
ing power. While the exact mechanism is not clear, Dr. Arthur J. Hartz speculated that nicotine 
or carbon monoxide in the smoke somehow poisons the heart and leads to heart failure. 


KAAIRDIYOWMAYAASPAXTHIY. AY /HAED NEHIVER HER4D AXV IHT BIXFOHSR, 
BAHT DHEH5R IHT WAHZ - LIH4STIXD AEZ (DHAX FOH5RM AXV /HAASRT DIHZTY5Z) 
DHAET FEH4LD (NAAT WAHS5N OHR TUW5S) - BAHT (AO7L THRIY5 AXV DHAX 
AASRTAXFIHSHUL /HAASRT ~~ RIXSIHSPIYINTS). (AH LIH5TUL RIXSER5CH) 
PROHDUW5ST (SAHM IH5NTRIHSTIHNX RIXZAHSLTS). AHKOHS5RDIHNX TUW (AEN 
AASRTIHKUL IHN DHAX NOWVEHSMBER EY2TH NAYSNTIYNEYTIYFOHIR NUW 
IYSNXGLIND JERS5NUL AXV MEHSDIXSIN), (SIHSGEREHT SMOWSKIHNX) KAO4ZIHZ 
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(DHIHS LIY5THUL DIHZIY5Z) DHAET WIY4KINZ (DHAX /HAA5RTS PAH4MPIHNX 
PAW2ER). WAYL (DHIY IHGZAE5KT MEHS5KINIXZUM) IHZ NAAT KLIY5R, DAA5KTER 
AA5RTHER JEY2 /HAASRTS SPEHS5KYULEYTIHD DHAET NIH5KAXTIYN OHR 
KAA5RBIN MUNAASKSAYD JTHN DHAX SMOW5K - SAH5M/HAW1 POY4ZINZ DHAX 
/HAASRT - AEND LIY4DZ TUW (/HAASRT FEYSLYER). 


CONCLUDING REMARKS 


This guide should get you off to a good start in phonetic writing for Narrator. The only way to 
get really proficient is to practice. Many people become good at it in as little as one day. Oth- 
ers make continual mistakes because they find it hard to let go of the rules of English spelling, 
so trust your ears. 


The More Technical Explanation 


The SoftVoice speech synthesis system is a computer model of the human speech production 
process. It attempts to produce accurately spoken utterances of any English sentence, given 
only a phonetic representation as input. Another program in the system, Translator, derives 
the required phonetic spelling from English text. Timing and pitch contour are produced 
automatically by the synthesizer software. 


In humans, the physical act of producing speech sounds begins in the lungs. To create a voiced 
sound, the lungs force air through the vocal folds (sometimes called the vocal cords), which are 
held under tension and which periodically interrupt the flow of air, thus creating a buzz-like 
sound. This buzz, which has a spectrum rich in harmonics, then passes through the vocal tract 
and out the lips, which alters its spectrum drastically. This is because the vocal tract acts as a 
frequency filter, selectively reinforcing some harmonics and suppressing others. 


It is this filtering that gives a speech sound its identity. The amplitude versus frequency graph 
of the filtering action is called the vocal tract transfer function. Changing the shape of the 
throat, tongue, and mouth retunes the filter system to accent different frequencies. 


The sound travels as a pressure wave through the air, and it causes the listener’s eardrum to 
vibrate. The ear and brain of the listener decodes the incoming frequency pattern. From this 
the listener can subconsciously make a judgment about what physical actions were performed 
by the speaker to make the sound. Thus the speech chain is completed, the speaker having 
encoded his physical actions on a buzz via selective filtering and the listener having turned the 
sound into guesses about physical actions by frequency decoding. 
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Now that we know how we do it, how does a machine do it? It turns out that the vocal tract is 
not random, but tends to accentuate energy in narrow regions called formants. The formant 
positions move smoothly as we speak, and it is the formant frequencies to which our ears are 
sensitive. So, luckily, we do not have to model throat, tongue, teeth and lips with our com- 
puter, we can imitate formant action. 


A good representation of speech requires up to five formants, but only the lowest three are 
required for intelligibility. We begin with an oscillator that produces a waveform similar to that 
which is produced by the vocal folds, and we pass it through a series of resonators, each tuned 
to a different formant frequency. By controlling the volume and pitch of the oscillator and the 
frequencies of the resonators, we can produce highly intelligible and natural-sounding speech. 
Of course the better the model, the better the speech; but more importantly, experience has 
shown that the better the control of the model’s parameters, the better the speech. 


Oscillators, volume controls and resonators can all be simulated mathematically in software, and 
it is by this method that the SoftVoice system operates. The input phonetic string 1s converted 
into a series of target values for the various parameters illustrated. A system of rules then 
operates on the string to determine things such as the duration of each phoneme and the pitch 
contour. Transitions between target values are created and smoothed to produce natural con- 
tinuous changes from one sound to the next. 


New values are computed for each parameter for every 8 milliseconds of speech, which produces 
about 120 acoustic changes per second. These values drive a mathematical model of the speech 
synthesizer. The accuracy of this simulation is quite good. Human speech has more formants 


than the SoftVoice model, but they are low in energy content. 


The human speech production mechanism is a complex and wonderful thing. The more we 
learn about it, the better we can make our computer simulations. Meanwhile, we can use syn- 
thetic speech as yet another computer output device to enhance the man/machine dialogue. 


Table of Phonemes 


Table 12-2 lists all the available phonemes. 
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Table 12-2: Phonemes 


Vowels 


Phoneme Example Phoneme Example 


LY beet IH bit 
EH bet AE bat 
AA hot AH under 
AO talk UH look 
ER bird OH border 
AX* about [X* solid 


*AX and [X should never be used in stressed syllables. 


Diphthongs 


Phoneme Example Phoneme Example 


EY made AY hide 
OY boil AW power 
OW low UW crew 
Consonants 
Phoneme Example Phoneme Example 
R red L yellow 
W away Y yellow 
M men N men 
NX sing SH rush 
S sail TH thin 
F fed ZH pleasure 
Z has DH then 
V very J judge 
CH check /C loch 
/H hole P put 
B but T toy 
D dog G guest 
K Commodore 
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Digits 1-9 
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Special Symbols 


Phoneme Example 
DX pity (tongue flap) 
Q kitt_en (glottal stop) 
Qx pause (silent vowel) 
RX car (postvocalic 
LX call R and L) 
Contractions 
(see text) 

UL = AXL 

IL = IXL 

UM = AXM 

IM = IXM 

UN = AXN 

IN = ‘DON 


Digits and Punctuation 


Syllabic stress, ranging from secondary through emphatic 


Period — sentence final character 
Question mark —sentence final character 


Dash — phrase delimiter 


Comma— clause delimiter 
Parentheses— noun phrase delimiters (see text) 


Chapter 13 


Serial Device 


This chapter describes software access to the serial port. The serial device is accessed via the 


standard system device-access routines and provides some additional functions specifically 
appropriate to use of this device. 


Introduction 


The serial device can be opened in either exclusive access mode or shared mode. It can be set to 
transmit and receive many different baud rates (send and receive baud rates are identical). It 
can support a seven-wire handshaking as well as a three-wire interconnect to a serial hardware 
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device. Handshaking and access mode must be specified before the serial device is opened. 
Other serial parameters can be specified using the SDCMD_SETPARAMS command after 
the device has been opened. 


Opening the Serial Device 


Typically, you open the serial device by using the following function calls: 


LONG error; 
struct Port *mySerPort; 
struct IOExtSer *mySerReq; 


/* create a reply port to which serial device can return the request */ 
mySerPort = CreatePort(” mySerial” ,O); 
if(mySerPort == NULL) exit(100); /* can’t create port? */ 


/* create a request block appropriate to serial * / 
mySerReq = (struct IOExtSer *)CreateExtIO(mySerPort, 
sizeof(struct IOExtSer)); 
if(mySerReq == NULL) goto cleanup]; /* error during CreateExtIO? */ 


mySerReq->io_SerF lags = 0; 

/* Accept the default, i.e., exclusive Access and XON/XOFF protocol 
* is enabled. Remaining flags all zero, see devices/serial.h 

* for bit-positions. Definitions included in this chapter. */ 


error = OpenDevice(”serial.device” ,0,mySerReq,0); 
if(error != 0) goto cleanup2; /* device not available? * / 


cleanup2: 

DeleteExtIO(mySerRegq,sizeof(struct IOExtSer)); 
cleanupI: 

DeletePort(mySerPort); 


The routines CreatePort() and DeletePort() are part of amiga.lib. Information about the 
routines CreateExtIO() and DeleteExtIO() can be found in the appendixes of the Amiga 
ROM Kernel Reference Manual: Exec. 


During the open, the only flags that the serial device pays any attention to are the 
shared/exclusive-access flag and the seven-wire flag (the seven-wire flag enables RS-232-C 
DTR/DSR,RTS/CTS handshaking protocol). All other bits in io_SerFlags are ignored. How- 


ever, for consistency, the other flag bits should be set to zero when the device is opened. 
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When the serial device is opened, it opens the timer device and then allocates an input buffer of 
the size last used (default and minimum = 512 bytes). As with any of the other serial port 
parameters, you can later change the value used for the read buffer size with the 
SDCMD_SETPARMS command. The OpenDevice() routine will fill the latest parameter 
settings into the io_Request block. 


Once the serial device is opened, all characters received will be saved, even if there is no current 
request for them. Note that a parameter change cannot be performed while an I/O request is 
actually being processed, because it would invalidate request-handling already in progress. 
Therefore you must ure SDCMD_SETPARAMS only when you have no serial I/O requests 
pending. 


Reading from the Serial Device 


You read from the serial device by sending your IORequest (IOExtSer) to the device with a 
read command. You specify how many bytes are to be transferred and where the data is to be 
placed. Depending on how you have set your parameters, the request may read the requested 
number of characters or it may terminate early. 


Here is a sample read command: 


char myDataArea([100]; 
my SerReq- >IOSer.io_Data = &myDataArea[0]; /* where to put the data */ 


my SerReq- >IOSer.io_Length = 100; /* read 100 characters * / 
my SerReq- >IOSer.io_Command = CMD_READ;/* say it is a read */ 
DoIO(mySerReq); /* synchronous request * / 


If you use this example, your task will be put to sleep waiting until the serial device reads 100 
bytes (or terminates early) and copies them into your read-buffer. Early termination can be 
caused by error conditions or by the serial device sensing an end of file condition. 


Note that the io_Length value, if set to -1, tells the serial device that you want to read a null- 
terminated string. The device will read all incoming characters up to and including a byte 
value of Ox00 in the input stream and will then report to you an io_Actual value that is the 
actual length of the string, excluding the 0 value. Be aware that you must encounter a O value 
in the input stream before the system fills up the buffer you have specified. The io_Length is, 
for all practical purposes, indefinite. Therefore, you could potentially overwrite system memory 
if you never encountered the null termination (zero value byte) in the input stream. 
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FIRST ALTERNATIVE MODE FOR READING 


As an alternative to DoIO() you can use SendIO() to transmit the command to the device. In 
this case, your task can go on to do other things while the serial device is collecting the bytes 
for you. You can occasionally do a CheckIO(mySerRegq) to see if the I/O is completed. 


struct Message *myIQO; 


/* same code as in above example, except: */ 


SendIO(mySerReq); 


/* do something */ 
/* (user code) */ 
myIO = CheckIO(mySerReq); 
if(myIO != FALSE) goto ioDone; /* this IO is done */ 


/* do something else * / 
/* (user code) */ 


WaitIO(mySerReq); 

mylO = mySerRegq; /* if had to wait, need a value for myIO */ 
} 

ioDone: 


Remove(mySerPort->mp_MsgList,myIO); 
/* use the Remove function rather than the GetMsg function */ 


/* now check for errors, and so on. */ 


The Remove() function is used instead of the GetMsg() function to demonstrate that you 
might have established only one port at which all of your I/O requests will be returned, and you 
may be checking each request, in turn, with CheckIO() to see if it has completed (maybe a 
disk request, a serial request and a parallel request, all simultaneously outstanding, all using 
SendIO() to transmit their commands to the respective devices). 


It is possible that while you are doing other things and checking for completion of I/O, one dev- 
ice may complete its operations and append its message block to your reply port while you are 
about to check the status of a later-arriving block. If you find that this later one has completed 
and you call GetMsg(), you will remove whichever message is at the head of the list. This 
message may not necessarily be the one you expect to be removing from the port. CheckIO() 
returns the address of the IORequest if the I/O is complete, and you can use this address for 
the Remove() function to remove the correct request block for processing and reuse. 
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SECOND ALTERNATIVE MODE FOR READING 


Instead of transmitting the read command with either DoIO() or SendIO(), you might elect to 
use BeginIO(), (the lowest level interface to a device) with the “quick I/O” bit set in the 
io_F lags field. 


/* same code as in read example, except: */ 


mySerReq- >IOSer.io_Flags = IOF_QUICK; /* use QUICKIO */ 
BeginIO(mySerReq); 


The serial device may support quick I/O for certain read requests. As documented in the 
“Input/Output” chapter in Amiga ROM Kernel Reference Manual: Exec, this command may 
be synchronous or asynchronous. Any write request always clears the quick I/O bit. Various 
read commands may or may not clear it, depending on whether or not quick I/O occurs. 


After executing the code shown above, your program needs to know if the I/O happened syn- 
chronously, and it must also test to see if the I/O took place. 


if((mySerReq->IOSer.io_Flags & IOF_QUICK) == 0) 
{ 
/* QUICKIO couldn’t happen for some reason, so it did it normally... 
* queued the request, cleared the QUICKIO bit, and used the equivalent 
* of SendIO. Might want to have the task doing something else while 
* awaiting the completion * of the I/O. After knowing it is done, must 
* remove the message from the reply port for possible reuse. 
*/ 
WaitIO(mySerReq); 
/* assumes single-threaded I/O, as compared to 
* the SendIO() example in the previous section * / 


j 
t 


/* If flag is still set, IO was synchronous, [ORequest was NOT appended 
* to the reply port and there is no need to remove the message from 


else 


* the reply port; continue on with something else. 
+ 
) 


} 


The way you read from the device depends on your need for processing speed. Generally the 
BeginIO() route provides the lowest system overhead when quick I/O is possible. However, if 
quick I/O did not work, it still requires some overhead for handling of the IORequest block. 
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TERMINATION OF THE READ 


Reading from the serial device can terminate early if an error occurs or if an end-of-file is 
sensed. You can specify a set of possible end-of-file characters that the serial device is to look 
for in the input stream. These are contained in an io_TermArray that you provide, using the 
SDCMD_SETPARAMS command. Note: io_TermArray is used only when EOF mode is 


selected. 


If EOF mode is selected, each input data character read into the user’s data block is compared 
against those in io_TermArray. If a match is found, the LORequest is terminated as com- 
plete, and the count of characters read (including the TermChar) is stored in io_Actual. To 
keep this search overhead as efficient as possible, the serial device requires that the array of 
characters be in descending order (an example is shown in the summary page in the ‘‘Device 
Summaries” appendix for SUCMD_SETPARAMS). The array has eight bytes and all must 
be valid (that is, do not pad with zeros unless zero is a valid EOF character). 


Fill to the end of the array with the least value TermChar. When making an arbitrary choice 
of EOF character(s), it is advisable to use the lowest value(s) available. 


Writing to the Serial Device 


You can write to the serial device as well as read from it. It may be wise to have a separate 
block for reading and writing to allow simultaneous operation of both reading and writing. The 
sample code below creates a separate reply port and request for writing to the serial device. 
Note that it assumes that the OpenDevice() function worked properly for the read. It copies 
the initialized read request block to initialize the write request block. Error-checking has been 
deliberately left out of this code fragment for brevity but should, of course, be provided in a 
functional program. 


/* code fragment to ”clone” an existing serial I/O request block instead of 
* opening the device once for read and once for write */ 


/* pointer to an existing serial read request block initialized by a 
* call to OpenDevice(SERIALNAME,0,mySerRegq,0) */ 

struct I[OExtSer *mySerReq; 

LONG 1; 

BYTE *b,*c; 


struct Port *mySerWritePort; /* pointer to a MsgPort at which to receive 
* replies to write requests * / 

struct IOExtSer *mySerWriteReq; /* pointer to a new request block for serial 
* communications * / 


388 Serial Device 


mySerWritePort = CreatePort(” mySerialWrite’” ,O); 


mySerWriteReq = (struct IOExtSer *)CreateExtIO(mySerWritePort, 
sizeof(struct IOExtSer)); 


b = (BYTE *)mySerReq; /* start of read request block */ 
c = (BYTE *)mySerWriteReq; /* start of write request block */ 


for(i=0; i< sizeof(struct IOExtSer); i++) 

*c++ = *b+-+; 
my Ser WriteReq- >IOSer.io_Message.mn_ReplyPort = mySerWritePort; 
/* clones the request block on a byte by byte basis */ 
/* Note: it might simply be easier here to have opened the serial device 
* twice. This would reflect the fact that there are two ”software entities” 
* that are currently using the device. However, if you are using exclusive 
* access mode, this is not possible and the request block must be copied anyway. 


*/ 


Note that this code would require the following clean-up at the termination of the program: 


cleanupWritelO: 
DeleteExtIO(mySerWriteReq); 
cleanup WritePort: 


DeletePort(mySerWritePort); 


Now, to perform a write: 


char dataToWrite[100]; 
my SerReq->IOSer.io_Data = &dataToWrite[0]; /* where to get the data */ 


mySerReq- >I1OSer.io_Length = n; /* write n characters */ 
my SerReq- >IOSer.io_Command = CMD_WRITE; /* say it is a write */ 
DoIO(mySerReq); /* synchronous request * / 


You can use the SendIO() or BeginIO() functions as well as DoIO(). The same warnings 
apply as shown above in the discussions about alternative modes of reading. 


Note that if io_Length is set to -1, the serial device will output your serial buffer until it 
encounters a value of Ox00 in the data. It transmits this 0 value in addition to the data to 


match the technique used for serial read shown above. (You can also read data zero- 
terminated). 
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Setting Serial Parameters 


You can control the following serial parameters. The parameter name within the serial data 
structure 1s shown in table 13-1. All of the fields described in this section are filled in when you 
call OpenDevice() to reflect the current settings of the serial device. Thus, you need not 
worry about any parameter that you do not need to change. 
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Parameter Name 


io_CtlChar 


io _ RBufLen 


io_ExtF lags 


io_Baud 


io _BrkTime 
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Table 13-1: Serial Parameters 


Characteristic It Controls 


Control characters to use for xON, xOFF, INQ, ACK respec- 
tively. Positioned within an unsigned longword in the sequence 
from low address to high as listed. INQ and ACK handshaking 
is not currently supported. 


Size of the buffer that the serial device should allocate for 
incoming data. Minimum size is 512 bytes. It will not accept a 
smaller value. This buffer is dynamically allocated by the serial 
device. If, as you do an SDCMD_SETPARAMS command, 
it senses a difference between its current value and the value of 
buffer size you request, it deallocates the old buffer and allo- 
cates a new one. Note that it discards all characters that may 
already be in that old buffer and that you may not have yet 
had a chance to read. Thus it is wise to make sure that you do 
not attempt buffer size changes (or any change to the serial 
device, for that matter) while any I/O is actually taking place. 


Reserved for future use. 


The real baud rate you wish to use. A long value from 110 to 
292,000. When a value of 110 is requested, it defaults to 112 
(the lowest value the hardware can support). Although baud 
rates above 19,200 are supported by the hardware, software 
overhead may limit your ability to ‘“‘catch”’ every single charac- 
ter that should be received. Output data rate, however, 1s not 
software-dependent. 


If you issue a break command, this variable specifies how long, 
in microseconds, the break condition lasts. This value controls 
the break time for all future break commands until modified by 


another SDCMD_SETPARAMS. 


io_TermArray 


io ReadLen 
io_WriteLen 
io _StopBits 


io SerF lags 


SERIAL FLAGS 


A byte-array of eight termination characters, must be in des- 
cending order. If EKOFMODE is set in the serial flags, this 
array specifies eight possible choices of character to use as an 
end of file mark. See the section above titled ‘‘Termination of 
the Read” and the SDCMD_SETPARAMS summary page 


in the “Device Summaries” appendix for more information. 
How many bits per read character; typically a value of 7 or 8. 
How many bits per write character; typically a value of 7 or 8. 


How many stop bits are to be expected when reading a charac- 
ter and to be produced when writing a character; typically 1. 
A value of 2 is allowed if io_ WriteLen = 7. 


Explained below; see ‘Serial Flags.” 


Bit Active Function 
0 low Busy 
1 low Paper out 
2 low Select 
3 low Data set ready 
4 low Clear to send 
5 low Carrier detect 
6 = low Ready to send 
7 ~~ low Data terminal ready 
8 high Read overrun 
9 high Break sent 
10 ~— high Break received 
11 high Transmit x-OFFed 
12 = high Receive x-OF Fed 
13-15 (not) (reserved ) 


Table 13-2 shows the flags that can be set to affect the operation of the serial device. Note that 
the default state of all of these flags is zero. 
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Flag Name 


SERB_XDISABLED 
SERB_EOFMODE 


SERB_SHARED 


SERB_RAD_BOOGIE 


SERB_QUEUEDBRK 
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Effect on Device Operation 


Disable XON-XOFF feature. 


Set this bit if you want the serial device to check I/O 
characters against io_TermArray and to terminate 
the ILORequest immediately if an end-of-file character 
has been encountered. Note: ‘This bit can be set and 
reset directly in the user’s IORequest (IOExtSer) 
block without a call to SDCMD_SETPARAMS. 


Set this bit if you want to allow other tasks to simul- 
taneously access the serial port. The default is 
exclusive-access. If someone already has the port, 
whether for exclusive or shared access, and you ask for 
exclusive-access, your OpenDevice() call will fail 


(should be modified only at OpenDevice()). 


If set, this bit activates high-speed mode. Certain peri- 
pheral devices (MIDI, for example) may require high 
serial throughput. Setting this bit high causes the serial 
device to skip certain of its internal checking code to 
speed throughput. In particular, it: 


- Disables parity checking 

- Bypasses XON/XOFF handling 

- Uses only 8-bit character length 

- Will not test for a break signal 

- Automatically sets SERB_XDISABLED bit 


Note that the Amiga is a multitasking system and has 
immediate processing of software interrupts. If there 
are other tasks running, it is possible that the serial 
driver may be unable to keep up with high data 
transfer rates, even with this bit set. 


If set, every break command that you transmit will be 
enqueued. This means that the current serial output 
commands will be executed in sequence. Then the 
break command will be executed, all on a FIFO (first in, 
first out) basis. If this bit is cleared (the default), a 
break command takes immediate precedence over any 
serial output already enqueued. When the break com- 
mand has finished, the interrupted request will continue 
(if it is not aborted by the user). 


SERB_7WIRE If set (should be established only at OpenDevice()), 
the serial device is to use a seven-wire handshaking for 
RS-232-C communications. Default is three-wire (pins 


2, 3, and 7). 
SERB_PARTY_ODD If set, selects odd parity. If clear, selects even parity. 
SERB_PARTY_ON If set, parity usage and checking is enabled. 


SETTING THE PARAMETERS 


You set the serial parameters by setting the flags and parameters as you desire and then 
transmitting the command SDCMD_SETPARAMS to the device. Here is an example: 


my SerReq- >IOSer.io_SerFlags &= ~ SERF_PARTY_ODD; /* ’and’ with inv¢ 
mySerReq- >IOSer.io_SerFlags |>= SERF_QUEUEDBRK | SERF_PARTY_ON; 
mySerReq->io_BrkTime = 500000; /* 500k microseconds = 1/2 second */ 

my SerReq- >IOSer.io_Command = SDCMD_SETPARAMS; 

DoIO(mySerReq); /* synchronous request * / 


The above command would set the bits for queued break and even parity while leaving the 
other flags unchanged. Notice the difference between the flag names and the flags that you 
actually set using C. “SERB...’’ is the name applied to the bit position within the flag word. 
“SERF...’’ is the name of a 1 bit in a mask at that bit position. 


Errors from the Serial Device 


The possible error returns from the serial device are listed in table 13-3. 
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Table 13-3: Serial Device Errors 


#define SerErr_DevBusy 
#define SerErr_BaudMismatch 
#define SerErr_InvBaud 
#define SerErr_BufErr 
#-define SerErr_InvParam 
#define SerErr_LineErr 
#-define SerErr_NotOpen 
#-define SerErr_PortReset 
#-define SerErr_ParityErr 
#-define SerErr_InitErr 
#define SerErr_TimerErr 
#define SerErr_BufOverflow 12 
#define SerErr_NoDSR 13 
#define SerErr_NoCTS 14 
#define SerErr_DetectedBreak 15 


Oeonoaa hh WD 
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Closing the Serial Device 
When the (final, if shared access) CloseDevice() is performed, the input buffer is deallocated, 
the timer device is closed, and the latest parameter settings are saved for the next open. 


Typically, you close the serial device with the following function call: 


CloseDevice(mySerReq); 


This assumes that the serial device has completed all activities you have requested and has 
returned all 1/O requests to you. 


When you have finished with the serial device, it is up to you to deallocate any memory and 
dependencies you might have used for the serial device communications. If you have used the 
techniques shown earlier in this chapter to establish the communications in the first place, your 
clean-up typically will consist of the following code: 
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cleanup2: 


DeleteExtIO(mySerRegq,sizeof(struct IOExtSer)); 
cleanuplL: 

DeletePort(mySerPort); 
cleanupWritelO: 

DeleteExtIO(mySerWriteReq); 
cleanupWritePort: 

DeletePort(mySerWritePort); 


Example Program 


Here is an example program that uses static rather than dynamic allocation of the IOExtSer 
request block. It assumes that you have connected a serial terminal device to the Amiga serial 
port, and it uses the baud rate you have established in Preferences. The program outputs the 
following status lines to the CLI window: 


Serial device opened and accepted parameters 

Testing character exact-count output thru SendWaitWrite 
Test string length of -1 (make system find end of string) 
Type 16 characters to send to Amiga... 


If no external terminal is attached, waits forever! 


and outputs the following lines to the external terminal: 


Device opened ok 


User counts characters in string to send, or if null-terminated string, says ‘-1’ 


Types 16 characters to send to Amiga 


At this point, you must type 16 characters on your external terminal. This sample program 
does not echo characters that you type, so you will not see anything more until all 16 have been 
typed. Finally the program will respond (to the external terminal) with: 


You typed these printable characters: 
<here it lists the 16 characters> 
End of test 

54321.....exit 
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Then the program exits, printing ‘““Test completed!” to the CLI window. 


# include ” exec /types.h” 

# include ” exec /nodes.h” 
#include ” exec/lists.h” 
#include ” exec /ports.h” 
#-include ” exec/libraries.h” 
#include ” exec /devices.h” 
#include ” exec /io.h” 
#include ” devices /serial.h” 


struct IOExtSer *lORser; 

struct MsgPort *port; 

char buffer(200]; 

extern struct MsgPort *CreatePort(); 
extern struct [ORequest *CreateExtIO(); 


/* Note: to run this program, you must have an external terminal, set 

* at 9600 baud, attached to the Amiga serial port. Additionally the 

* serlal.device file must be located in the directory currently 

* assigned to DEVS: (to check this, in AmigaDOS, type: ASSIGN 

* then check the directory (usually the boot CLI disk volume, devs directory.) 


a 


main() 

{ 
int error; 
int actual; 
unsigned long rb]; 
unsigned long brk; 
unsigned long baud; 
unsigned char rwl; 
unsigned char wwl: 
unsigned char sf; 
unsigned long t0; 
unsigned long tl; 


/* SET UP the message port in the I/O request */ 
port == CreatePort (SERIALNAME,0); 
if (port =— NULL) { 
printf{(”\nProblems during CreatePort”); 
exit(100); 


j 


/* Create the request block for passing info 
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open: 


* to and from the serial device. */ 


IORser = (struct IOExtSer *)CreateExtIO(port,sizeof(struct IOExtSer)); 
if (IORser == NULL) 


printf(”\nProblems during CreateExtIO” ); 
goto cleanupl1; 


/* OPEN the serial.device */ 

if ((error = OpenDevice (SERIALNAME, 0, [ORser, 0)) != 0) { 
printf (”Serial device did not open, error = %1d” ,error); 
goto cleanupl1; 


} 


/* SET PARAMS for the serial.device */ 


rb] = 4096; 
rwl == 0x08; 
wwl = 0x08; 
brk = 750000; 
baud= 9600; 
sf = 0x00; 


tO = 0x51040303; 
tl = 0x03030303; 


if ((error = SetParams (JORser,rbl,rwl,wwl,brk,baud,sf,t0,t1)) !== 0) { 
printf (’Set parameters command returned an error: %1ld” ,error); 
goto cleanup2; 


} 


printf(” \nSerial Device opened and accepted parameters” ); 
WriteSer (IORser,” \n\015Device opened ok\n\015”, -1); 


printf(”\nTesting character exact-count output thru SendWaitWrite” ); 
SendWaitWrite (IORser, 


”User counts characters in string to send\n\015”, 42); 


printf(”\nTest string length of -1 (make system find end of string)” ); 
SendWaitWrite (IORser, 
or if null terminated string, say ’-1’\n\015”, -1); 


printf(”\nType 16 characters to send to amiga...” ); 


printf(” \nIf no external terminal is attached, waits forever!!” ); 


WriteSer (IORser, 
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”\n\015Type 16 characters to send to amiga\n\015”, -1); 
actual = ReadSer (IORser,buffer,16); 
WriteSer (IORser, 

”\n\015You typed these printable characters:\n\015”, -1); 
WriteSer (IORser,buffer, actual); 
WriteSer (IORser,”\n\015End of test\n\015”, -1); 
WriteSer (IORser,” 54321.....exit\n\015”, 16); 
printf(”\nTest completed!\n” ); 


/* CLOSE the serial.device */ 
cleanup2: 

CloseDevice (IORser); 
cleanupl: 

DeletePort (port); 

exit (0); 


/* SERIAL I/O functions */ 
SetParams(io,rbuf_len,rlen,wlen,brk,baud,sf,ta0,ta1) 


struct IOExtSer *io; 
unsigned long rbuf_len; 
unsigned char rlen; 
unsigned char wlen; 
unsigned long brk; 
unsigned long baud; 
unsigned char sf; 
unsigned long ta0; 
unsigned long tal; 


{ 


int error; 

10- >10_ReadLen = rlen; 

io- >10_BrkTime = brk; 

10- >10_Baud = baud; 

io- >10_WriteLen = wlen; 

10- >10_StopBits = 0x01; 

10- >io_RBufLen == rbuf_len; 
i0- >io_SerF lags == St: 


io- >1OSer.io_Command = SDCMD_SETPARAMS; 
io- >1i0o_TermArray.TermArray0O = ta0; 
io- >io_TermArray.TermArrayl = tal; 
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if ((error = DolO (io)) != 0) { 


printf (”serial.device setparams error %ld \n”, error); 


return (error); 


} 


ULONG ReadSer(io,data,length) 
struct IOExtSer *10; 
char *data; 


ULONG length; 
{ 


int error; 


io- >1OSer.io_Data = (APTR)data; 
io- >1OSer.io_Length = length; 
10- > lOSer.io_Command = CMD_READ; 


if ((error = DolO (io)) != 0) { 


printf (”serial.device read error %ld \n”, error); 


return (io- >IOSer.io_Actual); 


WriteSer(io,data, length) 
struct IOExtSer +10; 
char *data; 

int length; 

{ 


int — error; 


io- >1OSer.io_Data = (APTR)data; 
io- >lTOSer.io_Length = length; 
10- > lOSer.io_Command = CMD_WRITE; 


if ((error = DolO (io)) != 0) { 


printf (”serial.device write error %ld \n”, error); 


return (error); 


} 


ULONG SendWait Write(io,data,length) 
struct IOExtSer *10; 

char *data; 

int length; 


Serial Device 399 


int error; 

io- >IOSer.io_Data = (APTR)data; 

io- >1OSer.io_Length = length; 

io- >IOSer.io_Command = CMD_WRITE; 
SendIO (io); 


if ((error = WaitIO (io)) != 0) { 
printf (”serial.device waitio error %ld \n”, error); 
} 


return (io- >IOSer.io_Actual); 
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Chapter 14 


Parallel Device 


This chapter describes software access to the parallel port. The parallel device is accessed via 


the standard system device access routines and provides some additional functions specifically 
appropriate to use of this device. 


Introduction 


The parallel device can be opened either in exclusive-access or shared mode. Other parallel dev- 


ice parameters can be specified using the PDCMD_SETPARAMS command after the device has 
been opened. 
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Opening the Parallel Device 


Typically, you open the parallel device by using the following function calls: 


LONG error; 
struct Port *myParPort; 
struct IOExtPar *myParReq; 


/* create a reply port to which parallel 

* device can return the request */ 

myParPort = CreatePort(”myParallel” ,O); 

if(myParPort == NULL) exit(100); | _/* can’t create port? */ 


/* create a request block appropriate to parallel */ 
myParReq = (struct IOExtPar *)CreateExtIO(myParPort, 
sizeof(struct IOExtPar)); 
if(myParReq === NULL) goto cleanup]; /* error during CreateExtIO? */ 


my ParReq->io_ParF lags = 0; | 
/* accept the default, i.e., exclusive access. Remaining flags all zero, 


* see devices/parallel.h for bit-positions. Definitions included in this 
* chapter. */ 


error = OpenDevice(” parallel.device” ,0,myParReq,0); 


if(error != 0) goto cleanup2; /* device not available? */ 
cleanup2: 

DeleteExtIO(myParRegq,sizeof(struct IOExtPar)); 
cleanupI1: 


DeletePort(myParPort); 


The routines CreatePort() and DeletePort() are part of amiga.lib. Information about the 
routines CreateExtIO() and DeleteExtIO() can be found in the appendixes of the Amiga 
ROM Kernel Reference Manual: Exec. 


The parallel device is disk-resident. If it has not yet been loaded from disk, it will be read from 


DEVS:parallel.device on the boot AmigaDOS disk. Its parameters will be set up from default 
values. 


During the opening process, the only flag used by the parallel device is the shared/exclusive- 
access flag. For consistency, however, the other flag bits should be set to zero when the device 
is opened. 
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When the parallel device is opened, it opens the timer device and fills the latest parameter set- 
tings into the io_Request block. The OpenDevice() routine will fill the latest parameter set- 
tings into the io_Request block. Note that a parameter change cannot be performed while an 
I/O request is being processed, because it would invalidate request handling already in progress. 
Therefore, you must use PDCMD_SETPARAMS only when you have no parallel I/O 
requests pending. 


Reading from the Parallel Device 


You read from the parallel device by sending your IORequest (IOExtPar) to the device with 
a read command. You specify how many bytes are to be transferred and where the data is to 
be placed. Depending on how you have set your parameters, the request may read the 
sequested number of characters, or it may terminate early. 


Here is a sample read command: 


char myDataArea([100]; 
my ParReq- >1OPar.io_Data = &myDataArea/(0]; /* where to put the data «/ 


my ParReq- >IOPar.io_Length = 100; /* read 100 characters */ 
myParReq- >IOPar.io_Command = CMD_READ; /* say it is a read */ 
DolO(myParReq); /* synchronous request * / 


If you use this example, your task will be put to sleep waiting until the parallel device reads 100 
bytes (or terminates early) and copies them into your read-buffer. Early termination can be 
caused by error conditions or by the parallel device sensing an end-of-file condition. 


Note that the io_Length value, if set to -1, tells the parallel device that you want to read a 
null-terminated string. The device will read all incoming characters up to and including a byte 
value of Ox00 in the input stream, then report to you an io_Actual value that is the actual 
length of the string, excluding the 0 value. Be aware that you must encounter a O value in the 
input stream before the system fills up the buffer you have specified. The io_Length 1s, for all 
practical purposes, indefinite. Therefore, you could potentially overwrite system memory if you 
never encountered the null termination (zero-value byte) in the input stream. 
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ALTERNATIVE MODE FOR READING 


As an alternative to DoIO(), you can use SendIO() to transmit the command to the device. 
In this case, your task can go on to do other things while the parallel device is collecting the 
bytes for you. You can occasionally do a CheckIO(myParRegq) to see if the I/O is completed. 


struct Message *myIO; 


/* same code as in above example, except: */ 


SendIO(myParReq); 


/* do something */ 
/* (user code) */ 
myIO = CheckIO(myParReq); 
if(myIO != FALSE) goto ioDone; /* this IO is done */ 


/* do something else * / 
/* (user code) */ 
WaitIO(myParRegq); 
mylO = myParRegq; /* if had to wait, need a value for myIO */ 


j 
ioDone: 
Remove(myParPort- >mp_MsgList,myIO); 
/* use the Remove function rather than the GetMsg function */ 


/* now check for errors, and so on. */ 


The Remove() function is used instead of the GetMsg() function to demonstrate that you 
might have established only one port at which all of your I/O requests will be returned, and you 
may be checking each request in turn with CheckIO() to see if it has completed. These 
requests could be, for example, a disk request, a parallel request, and a serial request, all simul- 
taneously outstanding and all using SendIO() to transmit their commands to the respective 
devices. 


It is possible that while you are doing other things and checking for completion of I/O, one dev- 
ice may complete its operations and append its message block to your reply port when you are 
about to check the status of a later-arriving block. If you find that this later one has completed 
and you call GetMsg(), you will remove the message at the head of the list. This message may 
not necessarily be the one you expect to remove from the port. CheckIO() returns the address 
of the IORequest if the I/O is complete, and you can use this address for the Remove() func- 
tion to remove the correct request block for processing and reuse. 
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TERMINATION OF THE READ 


Reading from the parallel device can terminate early if an error occurs or if end of file is sensed. 
You can specify a set of possible end-of-file characters that the parallel device is to look for in 
the input stream. These are contained in an io_TermArray that you provide, using the 
PDCMD_SETPARAMS command. Note: io_TermArray is used only when EOF mode is 


selected. 


If EOF mode is selected, each input data character that is read into the user’s data block is 
compared against those in io_TermArray. If a match is found, the I[ORequest is terminated 
as complete, and the count of characters read (including the TermChar) is stored in 
io_Actual. To keep this search overhead as efficient as possible, the parallel device requires 
that the array of characters be in descending order (an example is shown in the 
PDCMD_SETPARAMS summary in the ‘“‘Device Summaries” appendix. The array has 
eight bytes and all must be valid (that is, do not pad with zeros unless zero is a valid EOF char- 
acter). Fill to the end of the array with the least-value TermChar. When making an arbi- 
trary choice of EOF character(s), it is advisable to use the lowest value(s) available. 


Writing to the Parallel Device 


You can write to the parallel device as well as read from it. It may be wise to have a separate 
IORequest block for reading and writing to allow both operations to take place simultaneously. 
If you wish to queue multiple commands to the parallel device (either read or write commands), 
it is acceptable to clone (copy) the I/O request block you receive from the call to 
OpenDevice(). A sample of cloning code is shown in the ‘‘Serial Device” chapter. 


To perform a write: 


char dataToWrite[100]; 
my ParReq->IOPar.io_Data = &dataToWrite[0]; /* where to get the data */ 


myParReq->IOPar.io_Length = n; /* write n characters */ 
my ParReq->IOPar.io_Command = CMD_WRITE;; /* say it is a write */ 
DoIO(myParReq); /* synchronous request */ 


You can use the SendIO() or BeginIO() functions as well as DoIO(). The same warnings 
apply as shown above in the discussions about alternative modes of reading. 


Note that if io Length is set to -1, the parallel device will output your parallel buffer until it 
encounters a value of Ox00 in the data. It transmits this 0 value in addition to the data to 
match the technique used for parallel read shown above. (You can also read data zero- 
terminated.) 
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Setting Parallel Parameters 


You can control the parallel parameters shown in table 14-1. The parameter name within the 
parallel data structure is shown below. All of the fields described in this section are filled in 
when you call OpenDevice() to reflect the current settings of the parallel device. Thus, you 
need not worry about any parameter that you do not need to change. 


Table 14-1: Parallel Parameters 


Parameter Name Characteristic It Controls 
io_PExtFlags Reserved for future use. 
io_PTermArray A byte-array of eight termination characters, must be in 


descending order. If EOFMODE is set in the parallel flags, 
this array specifies eight possible choices of character to 
use as an end-of-file mark. See the 
PDCMD_SETPARAMS summary page in the ‘‘Device 
Summaries” appendix and the section above titled ‘“Term1- 
nation of the Read” for more information. 


io_ParF lags Explained below; see “Parallel Flags.”’ 


PARALLEL FLAGS 


The flags shown in table 14-2 can be set to affect the operation of the parallel device. Note that 
the default state of all of these flags is zero. 
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Table 14-2: Parallel Flags 


Flag Name Effect on Device Operation 


PARB EOFMODE Set this bit if you want the parallel device to check I/O 
characters against io_TermArray and terminate the 
TORequest immediately if an end-of-file character has 
been encountered. Note: This bit can be set and reset 
directly in the user’s IORequest (IOExtPar) block 
without a call to PDCMD_ SETPARAMS. 


PARB SHARED Set this bit if you want to allow other tasks to simul- 
taneously access the parallel port. The default is ex- 
clusive access. If someone already has the port, whether 
for exclusive or shared access, and you ask for exclusive 
access, your OpenDevice() call will fail (should be 
modified only at OpenDevice()). 


SETTING THE PARAMETERS 


You set the parallel parameters by setting the flags and parameters as you desire and then 
transmitting the command PDCMD_SETPARAMS to the device. Here is an example: 


my ParReq- >IOPar.io_ParFlags &= _ PARF_EOFMODE; 
/* “and” with inverse * / 

my ParReq- >IOPar.io_Command = PDCMD_SETPARAMS; 

DoIO(myParReq); /* synchronous request * / 


The above command would cancel EOFMODE (use of the io_TermArray), leaving the other 
flags unchanged. Notice the difference between the flag names and the flags that you actually 
set using C. “PARB...”? is the name applied to the bit position within the flag word. 
“PARF...” is the name of a 1 bit in a mask at that bit position. 


Errors from the Parallel Device 


The possible error returns from the parallel device are listed in table 14-3. 
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Table 14-3: Parallel Device Errors 


#define ParErr_DevBusy 
#define ParErr_BufToBig 
#define ParErr_InvParam 
#define ParErr_LineErr 
#define ParErr_NotOpen 
#define ParErr_PortReset 
#define ParErr_InitErr 
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Closing the Parallel Device 


When the (final, if shared access) CloseDevice() is performed, the timer device is closed, and 
the latest parameter settings are saved for the next open. 


Typically, you close the parallel device with the following function call: 


CloseDevice(myParReq); 


This assumes that the parallel device has completed all activities you have requested and has 
returned all I/O requests to you. When you have finished with the parallel device, it is up to 
you to deallocate any memory and dependencies you might have used for the parallel device 
communications. If you have used the techniques shown earlier in this chapter to establish the 
communications in the first place, your clean-up typically will consist of the following code: 


cleanup2: 

DeleteExtIO(myParRegq,sizeof(struct IOExtPar)); 
cleanupIL: 

DeletePort(myParPort); 
cleanupWrritelO: 

DeleteExtIO(myParWriteReq); 
cleanupWritePort: 

DeletePort(myParWritePort); 
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Example Program 


Here is an example program that uses static rather than dynamic allocation of the IOExtPar 
request block. It assumes that you have connected a parallel I/O device to the Amiga parallel 


port. 


#include ” exec/types.h” 
#include ” exec/nodes.h” 
# include ” exec/lists.h” 
#include ”exec/ports.h” 
#include ” exec/libraries.h” 
#include ” exec/devices.h” 
#include ”exec/io.h” 


# include ” devices /parallel.h” 


struct IOExtPar IORpar; 

struct MsgPort *port; 

char buffer|64000); 

extern struct MsgPort *CreatePort(); 


main() 

{ . 
int error; 
int actual; 
unsigned char pflags; 
unsigned long pt0; 
unsigned long ptl; 


open: 
/* OPEN the parallel.device */ 
if ((error = OpenDevice (PARALLELNAME, 0, &IORpar, 0)) != 0) { 
printf ("bad news %ld on Open \n”, error); 
exit (error); 


} 


/* SET UP the message port in the I/O request */ 
port = CreatePort (PARALLELNAME,0O); 


IORpar.lOPar.io_Message.mn_ReplyPort — port; 


/* SET PARAMS for the parallel.device */ 
pflags = PARF_EOFMODE; 
ptO = 0x51040303; 
ptl — 0x03030303: 
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if ((error = setparams (pflags,pt0,pt1)) != 0) { 
printf ("bad news %ld on setup \n”, error); 
DeletePort(); 
exit (error); 


} 


actual = readPar (buffer,60000); 


/* CLOSE the parallel.device */ 
CloseDevice (&I1ORpar); 
DeletePort (port); 
exit (0); 


j 
/* PARALLEL I/O functions */ 
setparams(pf,ta0,tal) 

unsigned char pf; 


unsigned long ta0; 
unsigned long tal; 


{ 
int error; 
IORpar.io_ParF lags = pf; 
lIORpar.[OPar.io_Command = PDCMD_SETPARAMS; 
IORpar.io_PTermArray.PTermArrayO = ta0; 
IORpar.io_PTermArray.PTermArrayl = tal; 
if ((error = DolO (&1ORpar)) != 0) { 
printf (” parallel.device setparams error %ld \n”, error); 
return (error); 
} 
readPar(data,length) 
char *data:; 
ULONG length; 
{ 
int error; 


TORpar.lOPar.io_Data = data; 
TORpar.lOPar.io_Length = length; 
IORpar.JOPar.io_Command = CMD_READ; 
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if (error = DolO (&IORpar)) != 0) { 
printf (” parallel.device read error %ld \n”, error); 


return (IORpar.[OPar.io_Actual); 
} 


writePar(data,length) 
char *data; 
int length; 


{ 


int error; 

1ORpar.lOPar.io_Data = data; 
JORpar.JOPar.io_Length = length; 
IORpar.JOPar.io_Command = CMD_WRITE; 


if ((error = DolO (&IORpar)) != 0) { 


printf (” parallel.device write error %ld \n”, error); 


return (error); 
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Chapter 15 


Printer Device 


Introduction 


There are four basic ways of doing output to a printer on the Amiga computer and three basic 
kinds of output you can send. You can send your output to these devices: 


o PRT:—the DOS printer device 
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o SER:—the DOS serial device 

o PAR:—the DOS parallel device 

Oo printer.device— to directly access the printer device itself 
Your output can take the following form: 


o <A character stream, consisting of commands and data (if sent through DOS or directly 
to the printer device) 


o A command (if sent directly to the printer device) 
o A graphics dump (also sent directly to the printer device) 


The following section explains the various possible access pathways to the printer itself, along 
with the advantages and disadvantages of each pathway. 


PRT:— THE AMIGADOS PRINTER DEVICE 


PRT: is the AmigaDOS printer device. By using the Workbench Preferences tool, you can 
direct the output to either a serial or parallel printer, which is the generic printer configured on 
the system. You may print (output) escape sequences to PRT: to specify the options you want. 
The escape sequences you send are interpreted by the printer driver and (usually different) 
escape sequences are forwarded to the printer. This is by far the easiest method for most appli- 
cations. PRT: may be opened just like any other AmigaDOS file. 


SER:— THE AMIGADOS SERIAL DEVICE 


SER: is the AmigaDOS serial device. If you “know” that the printer is connected to the serial 
port (you should not) and you “know” what kind of printer it is (again, you should not) then 
you could use AmigaDOS to open SER: and output characters to it, causing it to print. This 
practice 1s strongly discouraged! Characters you send are not examined or converted. 


PAR:— THE AMIGADOS PARALLEL DEVICE 


PAR: is the AmigaDOS parallel device. The warnings given in the paragraph above apply here 
as well. 
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THE PRINTER DEVICE 


By opening the Exec printer device directly, you have full control over the printer. You can 
either send escape sequences as shown in the command definitions table below for printer con- 
trol or call the RawWrite() routine to send raw characters directly to your printer with no 
processing at all. Using this technique would be similar to sending raw characters to SER: or 
PAR: from AmigaDOS (but you do not need to know which one is connected to the printer). 
Also note that all “commands” to the printer transmitted through the DOS printer access path 
must take the form of a character stream. Direct access to the printer device allows you to 
transmit other commands, such as reset or flush or, for graphics dumps, DumpRPort() (dump 
a raster to a graphics-capable printer). 


Printer Device Output 


The printer device can be thought of as kind of a filter, in that some printers respond in one 
way to a command output and some respond in another. The printer device, as a standard 
printer interface, recognizes command sequences. Depending on the _ printer-dependent 
configuration that is currently loaded (by the Preferences tool), the printer device either ignores 
the command sequences or perhaps translates them into an entirely different sequence that this 
printer can actually understand and obey. 


Opening the AmigaDOS Printer Device 


You can open the DOS printer device just as though it were a normal DOS output file. Here is 
an example program segment that accomplishes this: 


struct File «file; 


file = Open( ”PRT:”, MODE_NEWFILE ); 
if (file == 0) exit(PRINTER_WONT_OPEN); 


Then, to print use code like this: 


actual_length = Write(file, dataLocation, length); 
where 


file 
is a file handle (see the AmigaDOS Developers Manual). 
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dataLocation 
is a pointer to the first character in the output stream you wish to write. 


length 
is the length of the output stream. 


actual_length 
is the actual length of the write. For the printer device, if there are no errors, this is 
likely to always be the same as the length of write requested. The only exception is if 
you specify a value of -1 for length. In this case, -1 for length means that a null (0) ter- 
minated stream is being written to the printer device. The device returns the count of 
characters written prior to encountering the null. If it returns a value of -1 as 
actual_length, there has been an error. 


Note that the Open() function could be called with SER: or PAR: if you do not want to have 
any character translation performed during the printer I/O. When the printer I/O is complete, 
and your program is ready to exit, you should close the device. Here is a sample function call 
that you could use: 


Close(file); 


Note that printer I/O through the DOS versions of the printer device must be done by a pro- 
cess, not by a task. DOS utilizes information in the process control block and would become 
confused if a simple task attempted to perform these activities. Printer I/O using the printer 
device directly, however, can be performed by a task. 


Data Structures Used During Printer I/O 


This section shows you how to set up for Exec printer I/O. There are three distinct kinds of 
data structures required by the printer I/O routines. Some of the printer commands, such as 
start, stop, and flush, require only an IOStdReq. Others, such as write, require a larger data 
structure called an IODRPReq (for “dump a RastPort’’) or IOPrtCmdReq (for “printer 
command request”). For convenience, the printer device has defined a single data structure, 
called printerIO, that can be used to represent any of the three different kinds of printer com- 
munications request blocks. 


The data structure type printerIO used in the following examples is a C-language union 


defined as: 
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union printerIO{ 

struct [OStdReq ios; 
struct I[ODRPReq iodrp; 
struct [OPrtCmdReq iopc; 


} 


This means that one memory area can be used to represent three distinct forms of memory lay- 
out for the three different types of data structures that must be used to pass commands to the 
printer device. Some of the commands are simple and can use an IOStdReq. Some of the 
commands require many more parameters and extend the basic I/O request block accordingly. 


If you use the function CreateExtIO(), you can automatically allocate enough memory to hold 
the largest structure in the union statement. 


Creating an I/O Request 


Printer I/O, like the I/O of other devices, requires that you create an I/O request message that 
you pass to the printer device for processing. The message contains the command as well as a 


data area. For a write, there will be a pointer in the data area to the stream of information you 
wish to write to the printer. 


The following program fragment can be used to create the message block that you use for 
printer communications. 


union printerIO *printerMsg; /* I/O request block pointer */ 
struct Port *printerPort; /* a port at which to receive * / 


printerPort = CreatePort(”my.print.port” ,O); 
printerMsg = (union printerIO *)CreateExtIO(printerPort, 
sizeof(union printerIO)); 


Error handling is not shown here. It is deferred to the example at the end of the chapter. 


The routine CreatePort(), which is part of amiga.lib, and the routine CreateExtIO() may be 
found in the appendixes of the Amiga ROM Kernel Reference Manual: Exec. 


Note that there are two additional kinds of I/O request blocks that, for some commands, must 
be prepared for sending to the printer. They are called IODRPReq and 1OPrtCmdRegq. 
Both are outlined in the include file devices/printer.h. The function call to CreateExtIO() 
returns a pointer to a memory block the size of the largest form of printer [ORequest. 
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Opening a Printer Device 


You open a path to the printer device using code like the following: 


int 
OpenPrinter(request) 
union printerIO *request; 


{ 
} 


return(OpenDevice(” printer.device” ,0,request,0)); 


This routine returns a value of zero if the printer device was opened successfully and a value 
other than zero if it did not open. 


Writing to the Printer 


There are three forms of writing to the printer. The first uses a character stream that you 
create, possibly containing escape sequences to be processed by the printer driver (‘‘PrintString”’ 
example) or containing just about anything else that is to be passed directly to the printer 
(‘“PrintRaw” example). The second form of write passes a command to the printer 
(““PrintCmd”’ example). The third form asks for a graphics dump of a drawing area (‘‘Printer- 
Dump” example). 


To write to the printer, you pass to the printer device the system standard command 
CMD_WRITE. Here are routines that can be used to send this command: 


/* Send a NULL-terminated string to the printer */ 


/* Assumes printer device is open and printerMsg is correctly initialized. 
* Watches for embedded ”escape-sequences’ and handles them as defined. 


*/ 


int 
PrintString(request,string) 
union printerIO *request; 
char *string; 
{ 
request- >ios.io_ Command = CMD_WRITE; 
request- >ios.io_ Data = string; 
request- >ios.io_Length = -1; 
/* if -1, the printer assumes it has been given 
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* a null-terminated string. 
“sh 
return(DolO(request)); 


} 


/* Send RAW character stream to the printer directly, 
* avoid ”escape-sequence” parsing by the device. 


*/ 


int 

PrintRaw/(request,buffer,count) 

union printerIO *request; /* a properly initialized request block */ 

char *buffer; /* where is the output stream of characters */ 
int count; /* how many characters to output */ 


{ 


/* queue a printer raw write */ 

request- >ios.io Command = PRD_RAWWRITE; 
request- >ios.io_Data = buffer; 

request- >ios.io_Length = count; 
return(DolIO(request)); 


PRINTER COMMAND DEFINITIONS 


The following table describes the supported printer functions. You can use the escape sequences 
with PRT: and the printer device. 


To transmit a command to the printer device, you can either formulate a character stream con- 
taining the material shown in the “Escape Sequence’’ column of table 15-1 below or send an 
TORequest to the printer device specifying which of these commands you wish to have per- 


formed. A sample routine for transmitting commands is shown immediately following the com- 
mand table. 


Again, recall that SER: and PAR: will ignore all of these and pass them directly on to the 
attached device. 
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Table 15-1: Printer Device Command Functions 


Cmd Escape Defined 

Name No. Sequence Function by: 
aRIs 0 ESCce Reset ISO 
aRIN 1 ESC#1 Initialize faa 
al ND 2 ESCD Lf ISO 
aNEL 3 ESCE Return, lf ISO 
aR] 4 ESCM Reverse If ISO 
aSGRO 5 ESC|Om Normal char set ISO 
aSGR3 6 ESC([3m Italics on ISO 
aSGR23 7 ESC|23m__sItalics off ISO 
aSGR4 8 ESC|4m Underline on ISO 
aSGR24 9 ESC[24m —_— Underline off Iso 
aSGR1 10 ESC/|1m Boldface on ISO 
aSGR22 11 ESO|[22m __ Boldface off ISO 
aSFC 12 ESC([nm Set foreground color ISO 

where n stands for a pair 

of ASCII digits, 3 followed 

by any number 0-9 
aSBC 13 ESC({nm Set background color ISO 

Where n stands for 

a pair of ASCII digits, 4 

followed by any number 0-9 
aSHORPO 14 ESC|0Ow Normal pitch DEC 
aSHORP2 15 ESC|2w Elite on DEC 
aSHORP 1 16 ESC[1w Elite off DEC 
aSHORP4 17 ESC|4w Condensed fine on DEC 
aSHORP3 18 ESC|3w Condensed off DEC 
aSHORP6 19 ESC|6w Enlarged on DEC 
aSHORPS5 20 ESC|5w Enlarged off DEC 
aDEN6 21 ESC|6”z Shadow print on DEC (sort of) 
aDEN5 22 ESC|[5” z Shadow print off DEC 
aDEN4 23 ESC|4”z Doublestrike on DEC 
aDEN3 24 ESC|3”z Doublestrike off DEC 
aDEN2 25 ESO|2”z NLQ on DEC 
aDEN1 26 ESC[1”z NLQ off DEC 
aSUS2 27 ESC |2v Superscript on +++ 
aSUS1 28 ESO[1v Superscript off +++ 
aSUS4 29 ESC|4v Subscript on See 
aSUS3 30 ESC|3v Subscript off ae 
aSUSO 31 ESC|0v Normalize the line eae 
aPLU 32 ESCL Partial line up ISO 
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aPLD 


al NTO 
aF NTI 
ak NT2 
aF NT3 
ak NT4 
aF NT5 
ak NT6 
ak NT7 
aF NTS8 
ak NT9 
aF NT10 


aPROP2 
aPROP1 
aPROPO 
alSs 
aJFY5 
aJ EF Y7 
aJF Y6 
aJF YO 
aJF Y3 
aJFY1 


aVERPO 
aVERPI 
aSLPP 
aPERF 
aPERFO 


aLMs 
aRMS 
alMs 
aBMSs 
as TBM 
aSLRM 
aCAM 


aHTS 
aVTS 
al BCO 
al BC3 
al BCI 
aT BC4 


al BCALL 
al BSALL 
ab X TEND 


33 


34 
30 
36 
37 
38 
39 
40 
4] 
42 
43 
44 


45 
46 
47 
48 
49 
50 
ol 
iy 
O38 
o4 


D9 
56 
o7 
o8 
a) 


60 
61 
62 
63 
64 
65 
66 


67 
68 
69 
70 
71 
72 
73 
74 
795 


ESCK 


ESC(B 
ESC(R 
ESC( 
ESC( 
ESC( 
ESC( 
( 
( 
( 
( 


<meera 


ESC 
ESC 
ESC 
ESC 
ESC(C 


ESO|2p 

ESO|1p 

ESC|Op 

ESC[n E 
ESO|5 F 
ESC|7 F 
ESC[6 F 
ESC(0 F 
ESC([3 F 
ESCi1 F 


ESC|0z 
ESO(1z 
ESC(nt 
ESC([ngq 
ESC|0q 


ESC#9 
ESC#0 
ESC#8 
ESC#2 
ESC{n;nr 
ESC|n;ns 
ESC#3 


ESCH 
ESCJ 
ESC|0g 
ESC|[3g 
ESC|1lg 
ESC|4g 
ESC#4 
ESC#5 
ESC|n” x 


Z 
J 
6 


Partial line down 


US char set 
French char set 
German char set 
UK char set 
Danish I char set 
Swedish char set 
Italian char set 
Spanish char set 
Japanese char set 
Norwegian char set 
Danish II char set 


Proportional on 
Proportional off 
Proportional clear 

Set proportional offset 
Auto left justify 

Auto right justify 
Auto full justify 

Auto justify off 
Letter space (justify) 
Word fill{auto center) 


1/8” line spacing 
1/6” line spacing 
Set form length n 
Perf skip n (n>0) 
Perf skip off 


Left margin set 
Right margin set 
Top margin set 
Bottom margin set 
T&B margins 
L&R margin 


Clear margins 


Set horiz tab 

Set vertical tabs 

Clr horiz tab 

Clear all h tab 

Clr vertical tabs 

Clr all v tabs 

Clr all h & v tabs 
Set default tabs 
Extended commands 


ISO 


DEC 
DEC 
DEC 
DEC 
DEC 
DEC 
DEC 
DEC 
+++ 
DEC 
+-—— 


44+ 

+++ 

+44 

ISO 

ISO 

ISO 

ISO 

ISO 

ISO (special) 
ISO (special) 


+++ 
+++ 
DEC 
oe 
bpp 


+++ 
at 
4b 
hfe 
DEC 
DEC 
md 


ISO 
ISO 
ISO 
ISO 
ISO 
ISO 
+++ 
+++ 
+++ 
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Legend: 


ISO 


DEC 


~ 


indicates that the sequence has been defined by the International Standards 
Organization. This is also very similar to ANSI x3.64. 


indicates a control sequence defined by Digital Equipment Corporation. 
indicates a sequence unique to Amiga. 


stands for a decimal number expressed as a set of ASCII digits, for example 12. 


Transmitting a Command to the Printer Device 


As noted above, to transmit a command to the printer device, you can either formulate an 
escape sequence and send it via the CMD_WRITE command, or you can utilize the command 
names and pass parameters and the command to the device. Here is a sample routine that uses 


the system command PRD_PRTCOMMAND to transmit a command to the device: 


int 


PrintCommand(request,command, pO, p1, p2, p3) 
union printerIO *request; 
int command, pO, pl, p2, p3;_ /* command and its parameters * / 


{ 


/* queue a printer command */ 

request- >iopc.io_Command = PRD_PRTCOMMAND; 
request- >iopc.io_PrtCommand = command; 

request- >iopc.io_Parm0O = pO; 
request->iopc.io_Parml = pl; 

request- >iopc.io_Parm2 = p2; 
request->iopc.io_Parm3 = p3; 

return(DolIO(request)); 


As an example, suppose you wanted to set the left and right margins on your printer to columns 
1 and 79 respectively. Here is a sample call to the PrintCommand() function for this pur- 


pose: 


PrintCommand(aSLRM, 1, 79, 0, 0); 
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Consult the function table. Wherever there is a value of ‘‘n’”’ to be substituted, it will be util- 
ized from the next available parameter for this command. Most of the commands in the table 
need no parameters; some need one and others need two. Few, if any, require more than two 
parameters; however, this function provides room for expansion. 


Dumping a RastPort to the Printer 


You can dump a RastPort (drawing area) to the printer by sending the command 
PRD_DUMPRPORT to the printer, along with several parameters that define how the dump 
is to be accomplished. The parameters shown in the sample dump function below are complete- 
ly described in the summary for DumpRPort() in the “Device Summaries” appendix. 


int 
DumpRPort(request,rastPort, colorMap, modes, sx,sy, sw,sh, de,dr, s) 

union printerIO *request; 

struct RastPort *rastPort; 

struct ColorMap *colorMap; 

ULONG modes; 

UWORD sx, sy, sw, sh; 

LONG dc, dr; 

UWORD s; 
{ 
request- >iodrp.io_ Command = PRD_DUMPRPORT; 
request- >iodrp.io RastPort = rastPort; 
request->iodrp.io_ColorMap = colorMap; 
request- >iodrp.io_Modes = modes; 
request->iodrp.io SrcX = sx; 
request- >iodrp.io_SrcY = sy; 
request- >iodrp.io_SrcWidth = sw; 
request- >iodrp.io SrcHeight = sh; 
request- >iodrp.io_DestCols = dc; 
request- >iodrp.io_DestRows = dr; 
request->iodrp.io_ Special = s; 
return(DoIO(request)); 


} 


As an example of this function, suppose you wanted to dump the current contents of the Work- 
bench screen to the printer. The typical program code shown below would accomplish it. Note 
that during the dump no other tasks should be writing to the screen, nor should you use the 
mouse to move windows or otherwise modify the screen appearance. 
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/* 
* Author: | Rob Peck, 12/1/85 
* Modified: Carolyn Scheppner, 04/08/86 


*k 


* This code may be freely utilized to develop programs for the Amiga. 


oy 


#include ”exec/types.h” 

#include ” intuition /intuition.h” 

#include ” devices/printer.h” 

#define INTUITION_WONT_OPEN 1000 


union printerlO { 
struct IOStdReq ios; 
struct IODRPReq iodrp; 
struct IOPrtCmdReq iopc; 


union printerlO *request; /* a pointer to a request block */ 


extern int DumpRPort(); 
extern struct [ORequest *CreateExtIO(); 
extern struct MsgPort *CreatePort(); 


struct IntuitionBase *IntuitionBase; 


main() 
{ 
struct Screen *screen; 
struct RastPort *rp; 
struct ViewPort *vp; 
struct ColorMap *cm; 
struct MsgPort *printerPort; /* at which to receive reply */ 
int modes,width,height,error; 


IntuitionBase = (struct IntuitionBase *)OpenLibrary( 
> intuition.library”, 0); 


if (IntuitionBase == NULL) exit(INTUITION_WONT_OPEN); 
screen = IntuitionBase->FirstScreen; /* ptr to front Screen */ 
vp = &screen->ViewPort; /* get screen’s ViewPort, from 

* which the ColorMap will be gotten */ 


rp = &screen->RastPort; /* get screen’s RastPort, which 
* is what gets dumped to printer */ 
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cm = vp->ColorMap; /* retrieve pointer to colormap for 
* the printer dump */ 

modes = vp->Modes; /* retrieve the modes variable */ 

width = screen->Width; /* retrieve width and */ 

height = screen->Height; /* height to print */ 


printerPort = CreatePort(” my.print.port” ,O); 
request = (union printerlO *)CreateExt]O(printerPort, 
sizeof(union printerIO)); 


error = OpenPrinter(request); 
if(error !== 0) goto cleanup2; 


Delay(300); /* 300/60 = 6 seconds delay before it starts */ 
error = DumpRPort( 
request, /* pointer to initialized request */ 
rp, /* RastPort pointer */ 
cm, /* color map pointer */ 
modes, /* low, high res, etc (display modes)*/ 
O, 0, /* x and y offsets into rastport */ 
width,height, /* source size */ 
0,0, /* dest size 0 because of Special */ 


SPECIAL_FULLCOLS | SPECIAL_ASPECT /* Special */ 
/* Special = print max width */ 
/* with proportional height */ 

); 


ClosePrinter(request); 


cleanup2: 
DeleteExtI]O(request, sizeof(union printerIO)); 
DeletePort(printerPort); 

cleanupl1: 
CloseLibrary(Intuition Base); 


\ /* end of demo screen dump */ 


GERAIS IGA ICCC COCCI ACC ICCC IRIS A AIK / 


/* printersupport.c rtns 
PERE OAC ESE ACESS GEO EIEaO EE SSE EEE CADIS AC IAA a / 


/* OPEN THE PRINTER */ 
int 
OpenPrinter(request) 
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union printerlO *request; 


{ 


return(OpenDevice(” printer.device” ,0,request,0)); 


} 


/* CLOSE THE PRINTER */ 
int 
ClosePrinter(request) 
union printerlO *request; 
{ 
CloseDevice(request); 
return(0); 


} 


/* Send a null-terminated string to the printer. Assumes printer device 
* is open and printerMsg is correctly initialized. Watches for embedded 
* »escape-sequences” and handles them as defined. 


a5 


int 
PrintString(request,string) 
union printerlO *request; 
char *string; 
{ 
request- >10s.10_Command = CMD_WRITE; 
request- >ios.io_Data = (APTR)string; 
request- >10s.i0o_Length = -1; 
/* if -1, the printer assumes it has been given a null terminated string. */ 
return(DolO(request)); 


j 


/* Send RAW character stream to the printer directly, 
* avoid ”escape-sequence” parsing by the device. 
+ / | 
int 
PrintRaw(request,buffer,count) 
union printerlO *request; /* a properly initialized request block */ 
char *buffer; /* where is the output stream of characters */ 
int count; /* how many characters to output */ 
{ 
/* queue a printer raw write */ 
request- >i0os.10_Command = PRD_RAWWRITE; 
request- >ios.io_Data = (APTR)buffer; 
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request- > 10s.10_Length = count; 


return(DolIO(request)); 


} 


/* Send Printer Command */ 
int 
PrintCommand(request,command, pO, pl, p2, p3) 
union printerlO *request; 
int command, pO, pl, p2, p3;_ +(/* command and its parameters */ 
‘ 
/* queue a printer command */ 
request- >iopc.io_ Command = PRD_PRTCOMMAND; 
request- >1opc.io_PrtCommand = command; 
request- > iopc.io_Parm0 = pO; 
request- >1opc.io_Parml = pl; 
request- >iopc.io_Parm2 = p2; 
request- >1opc.io_Parm3 = p3; 
return(DolO(request)); 


} 


ADDITIONAL NOTES ABOUT GRAPHICS DUMPS 


The print command accepts a “use the largest area you have”’ specification that looks at the 
Preferences active print width and active print height to bound the size of the print. These 
values are specified as a character count and a character size specification. Thus, the width of 
the print is bounded by the number of inches specified by the following equation: 
(RIGHT_MARGIN - LEFT_MARGIN + 1) / CHARACTERS_PER_INCH. The height is 
specified by the equation: LENGTH / LINES_PER_INCH. 


NumRows in the printer tag refers to the number of dots in the graphics print element, and 
can be used by graphics render code to determine how much buffer space is needed to compose a 
line of graphics output. It has not been used in practice; the number has instead been hard cod- 
ed into the render function specific to the printer. 


If the printer for which you are developing can be set to unidirectional mode under software 
control, we recommend that you put this in the initialization code for the printer (see case 0 
Master Initialization, below). This produces better-looking printouts and under most conditions 
(believe it or not) a faster printout. 


Printer Device 427 


Creating a Printer Driver 


Creating a printer-dependent code fragment for the printer device involves writing the data 
structures and code, compiling and assembling it, and linking it to produce an Amiga object 
binary. file. The first piece in that file is the PrinterSegment structure described in 
devices/prtbase.h and devices/prtbase.1 (which is pointed to by the BPTR returned by the 
LoadSeg() of the object file). 


You specify the printer-dependent object file to load by specifying ‘‘custom printer’’ in Prefer- 
ences and filling in the custom printer name with the name of the object file (relative to the 
directory DEVS:printers/ ). 


The printer-dependent code PrinterSegment contains the PrinterExtendedData (PED) 
structure (also described in devices/prtbase.h and devices/prtbase.t at the beginning of the ob- 
ject). The PED structure contains data describing the capabilities of the printer, as well as 
pointers to code and other data. Here is the assembly code for a sample PrinterSegment, 
which would be linked to the beginning of the sequence of files describing the printer-dependent 
code fragment. 


AEE He 2 a aK te ee 2 2 2 2 oa 2c 2k 2 2 2K Kc ke Fe 2K 2k 2 2 oa ic 2k 2 2 og ic ke 2k 2K akc 2 ok ke 2k 2k oe oc kc 2c 2 oi og og ic 2c of 2c 2c 2 2k 2 2 ok ok ok ok 
* 


* printer device dependent code tag 
* 


De 2 2 2 2 OE Ee I I ke 2k 2 IE 6 2K Ee 2 2 ke 2 2 2 2 oe 2K 2 2k Ke 2 2 2 2K 2 2 2 2 2 2 ic 2c oc 2 2 2 oe fe ke 2 2K og kc 2 ok oc ok 2 2k 


; named sections are easier to exactly place in the linked file 
SECTION custom 


INCLUDE ” exec/types.1” 
INCLUDE ” exec /nodes.1” 


INCLUDE *revision.1” ‘contains VERSION & REVISION 


INCLUDE ” devices/prtbase.i” 


Kann--= Imported Names ----------------------------------------------- 
XREF _Init 
XREF _Expunge 
XREF _Open 
XREF _Close 
XREF _Command Table 
XREF _DoSpecial 
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XREF _Render 
*------ Exported Names ----------------------------------------------- 
XDEF _PEDData 


2k OK Rk KKK KKK KOK RK KG KK oR Ka a ko ak kk ok kok ok ok ok 2 ok 


; In case anyone tries to execute this 


MOVEQ #0, D0 
RTS 
DC.W VERSION 
DC.W REVISION 
_PEDData: 
DC.L printerName 
DC.L _Init 
DC.L _Expunge 
DC.L _Open 
DC.L _Close 
DC.B PPC_BWGFX ; PrinterClass 
DC.B PCC_BW - ColorClass 
DC.B 80 - MaxColumns 
DC.B 1 ; NumCharsSets 
DC.W 8 - NumRows 
DC.L 960 ; MaxXDots 
DC.L 0 >; MaxYDots 
DC.W 120 ; XDotsInch 
DC.W 82 - YDotsInch 
DC.L _Command Table - Command Strings 
DC.L _DoSpecial ; Command Code 
DC.L _Render ; Graphics Render 
DC.L 30 ; Timeout 
printerName: 
DC.B ‘Custom Printer Name’ 
DC.B 0) 
EVEN 


The printer name should be the brand name of the printer that is available for use by programs 
wishing to be specific about the printer name in any diagnostic or instruction messages. The 
four functions at the top of the structure are used to initialize this printer-dependent code: 


(*(PED-> ped_Init))(PD); 


This is called when the printer-dependent code is loaded and provides a pointer to the 
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printer device for use by the printer-dependent code. It can also be used to open up 
any libraries or devices needed by the printer-dependent code. 


(*(PED->ped_Expunge))(); 
This is called immediately before the printer-dependent code is unloaded, to allow it to 
close any resources obtained at initialization time. 


(*(PED->ped_Open))(ior); | 
This is called in the process of an OpenDevice() call, after the Preferences are read 
and the correct primitive I/O device (parallel or serial) is opened. It must return zero if 
the open is successful, or nonzero to terminate the open and return an error to the user. 


(*(PED-> ped_Close))(ior); 
This is called in the process of a CloseDevice() call to allow the printer-dependent 
code to close any resources obtained at open time. 


The pd_ variable provided as a parameter to the initialization call is a pointer to the 
PrinterData structure described in devices/prtbase.h and devices/prtbase.i. This is also the 
same as the io_Device entry in printer I/O requests. 


pd_SegmentData 
This points back to the PrinterSegment, which contains the PED. 


pd_PrintBuf 


This is available for use by the printer-dependent code —it is not otherwise used by the 
printer device. 


(*pd_PWrite)(data, length); 
This is the interface routine to the primitive I/O device. This routine uses two I/O re- 
quests to the primitive device, so writes are double-buffered. The data parameter points 
to the byte data to send, and the length is the number of bytes. 


(*pd_PBothReady)(); 
This waits for both primitive I/O requests to complete. This is useful if your code does 
not want to use double buffering. If you want to use the same data buffer for successive 
pd_PWrites, you must separate them with a call to this routine. 


pd_Preferences 


This is the copy of Preferences in use by the printer device, obtained when the printer 
was opened. 


The timeout field is the number of seconds that an I/O request from the printer device will 
remain posted and unsatisfied to the primitive I/O device (parallel or serial) before the timeout 


requester is presented to the user. This value should be large enough to avoid the requester 
during normal printing. 
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SAMPLE CODE 


To help you in developing custom printer drivers for the Amiga, four sets of source files have 
been included as a part of this document. The files include inzt.asm, printertag.asm, data.c, 
render.c, and dospecial.c. 


Four sets of files for four different types of printers are provided: 


diablo_c - an example of a ymcb color printer 

epson - an example of a b/w printer 

okimate20 - an example of a ymc_bw printer (has two render.c functions) 
hpplus - an example of a single-sheet, multiple-density printer 


The source files for the hpplus includes one additional C-language source, named density.c. 


In addition, you will also need certain files that are common to all printer drivers. These are 
called macros.1 and are printer assembly code macros that inzt.asm uses. All of these files are in 
the “Printer Device Source Code”’ appendix of this manual. 


WRITING A GRAPHICS PRINTER DRIVER 


Designing the graphics portion of a custom printer driver consists of two steps: writing a 
printer-specific render.c function, and replacing the printer-specific values in printertag.asm. 
Note that a printer that does not support graphics has a very simple form of Render(); it re- 
turns an error. Here is sample code for Render() for a non-graphics printer (typically, an al- 
phacom or diablo_630): 


#include ”exec/types.h” 
#include ”devices/printer.h” 
int 

Render() 

{ 


} 


return(PDERR_NOTGRAPHICS); 


The following section describes the contents of a typical driver for a printer that actually sup- 
ports graphics. The example code for the Epson printer, contained in the “Printer Device 
Source Code” appendix, shows a typical Render() function based on this description. 
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Render.c 


This function is the main printer-specific code module and consists of six parts: 
o Master initialization 
o Pixel rendering 
o Dumping a pixel buffer to the printer 
o Clearing and initializing the pixel buffer 
o Closing down 
o Density selection 


Master Initialization (case 0). When this call is made, you are passed the width (in pixels) 
in x and the height (in pixels) in y of the picture as it should appear on the printer. Note that 
the printer non-specific code (using the printer-specific values in printertag.asm (that will be dis- 
cussed later), has already verified that these values are within range for the printer. It is recom- 
mended that you use these values to allocate enough memory for a temporary buffer in which to 
build a command buffer for the printer. The buffer size needed is dependent on the specific 
printer, the width (usually), and the height (sometimes). In general, the buffer represents the 


commands and data required for one pass of the print head and usually takes the following 
form: 


<start gfx cmd> <data> <end gfx cmd> 


where: 


<start 
is the command required to define the graphic dump for each line. 


<data> 
is the binary data. 


<end 
is a terminator telling the printer to print the data (usually a carriage return). 


For color printers, enough buffer space must usually be allocated for each different color ribbon, 


ink, and so on that the printer offers (the okimate-20 and diablo_c-150 are provided as examples 
of this). Please refer to the sample drivers. 
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The example render.c functions use double buffering to reduce the dump time, which is why the 


AllocMem() call is for 


(BUFSIZE times two) 


where BUFSIZE represents the amount of memory for one entire print cycle (usually one pass of 
the print head). 


Printers that would do more than one pass of the print head on a dump call are those that have 
to do a pass for each different main color that they want to lay down on the paper (like the 
Okidata-20 with three colors and the Epson_jx-80 with four colors). A printer such as the 
Diablo_c-150 that can lay down all the colors in a single pass needs to do only one pass. 


The number of passes the printer has to do is irrelevant to you. This topic was introduced 
mainly to illustrate the true meaning of the term ‘“‘one print cycle.’’ You want to send the 
printer an entire print cycle to allow the main non-printer-specific driver to continue onward, 
computing the values for the next print cycle while the printer is printing the previous dots. 
This is why you will find double buffering used in the example driver code. 


Any other initialization that the printer requires should also be done at this time. It is advis- 
able that you also do a reset command so that you know what state the printer is in before you 
try to send it any further commands. 


In addition, after performing a reset command it is advisable to send no other commands for at 
least one second to allow the printer to “‘calm down’’. Waiting after a reset is strongly recom- 
mended. The function PWait(seconds,microseconds) has been provided in the wazt.asm file 
(see the “Printer Device Source Code” appendix) for this purpose. The wazt.asm file must be 
assembled and linked into your custom printer device code. 


Render Pixel (Case 1). When this call is made, your routine will be passed the x,y position of 
a single pixel and its color type. Note that the x,y value is an absolute value and you will have 
to do some modulus math (usually an AND) to compute the relative pixel position in your 
buffer. The absolute values will range from O to width-1 for x and O to height-1 for y. The 
color types are O-black, l-yellow, 2-magenta, and 3-cyan. Currently there is no provision for an 
RGB (red-green-blue) printer. 


Dump Buffer to Printer (Case 2). When this call is made, you must send the buffer to the 
printer. As it now stands, there should be no need for you to change this routine. It should be 
common to all printers. It simply sends the buffer that you have been filling (via case 1) to the 
printer. 


You would want to change this routine only if you need to do some post-processing on the 
buffer before it is sent to the printer. For example, if your printer uses the hexadecimal number 
$03 as a command and requires that you send $03 $03 to send $03 as data, you would probably 
want to scan the buffer and expand $03’s to $03 $03. Of course, you’ll need to allocate space 
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somewhere in order to expand the buffer. 


Because the printer driver does not send you the blank pixels, you must initialize the buffer to 
values for blank pixels (usually 0). Clearing the buffer should be the same for all printers. Ini- 
tializing the buffer is printer-specific, and it includes placing the printer-specific control codes in 
the buffer ahead of and behind where the data will go. 


Closing Down (Case 3). When this call is made you must wait for the print buffers to clear 
and then de-allocate the memory. This routine should be common to all printers. It simply 
waits for both buffers to empty, and then deallocates the memory that they used. There should 
be no need for you to change this routine. If you do change it, however, make sure that the 
amount of memory allocated for case 0 is deallocated by this routine. 


Pre-Master Initialization (Case 4). Currently this option is implemented only on the 
HPLaserJet and HPLaserJet PLUS printers, although the call is made to each printer-specific 
driver. Ignoring it causes no problems as the call is made simply to give you a chance to select 
a different density from the default one. You should note that this call is made before the mas- 
ter initialization call (case 0) and gives you a chance to alter any variables that the master ini- 
tialization may use to program the printer. Refer to the HPLaserJet PLUS printer driver for an 
example of density selection. 


Printertag.asm 


The printer-specific values that need to be filled in here are as follows: 


Max XDots 


the maximum number of dots the printer can print across the page. 


Max YDots 
the maximum number of dots the printer can print down the page. Generally, if the 
printer supports roll or form feed paper, this value should be O indicating that there is 
no limit. If the printer has a definite y dots maximum (as the HPLaserJet does), this 
number should be entered here. 


XDotsInch 
the dot density in x (for example, 120 dpi). 


YDotsInch 
the dot density in y (for example, 144 dpi). 


PrinterClass 
the printer class the printer falls into. Current choices are: 
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PPC_BWALPHA - alphanumeric, no graphics. 
PPC_BWGFX - black&white (only) graphics. 
PPC_COLORGFX - color (and maybe b/w) graphics. 


ColorClass 
the color class the printer falls into. Current choices are: 


PCC_BW - Black &White only (for example, EPSON). 
PCC_YMC - Yellow Magenta Cyan only. 
PCC_YMC_BW - Yellow or Black& White but not both 
(for example, Okimate 20). 
PCC_YMCB - YellowMagentaCyanBlack (for example, Diablo_c-150). 


NumRows 
the number of pixel rows printed by one pass of the print head. This number is used by 
the non-printer-specific code to determine when to make a case 2 (see above) call to 


you. You have to keep this number in mind when determining how big a buffer you’ll 
need to store one print cycle’s worth of data. 


WRITING AN ALPHANUMERIC PRINTER DRIVER 


This alphanumeric section 1s meant to be read with the alpha listing for the EpsonX80 and Dia- 
blo Adv 25 close at hand. 


The alphanumeric portion of the printer driver is designed to convert ANSI x3.64 style com- 
mands into the specific escape codes required by each individual printer. For example, the 
ANSI code for italics on is ESC[3m. The Epson FX80 printer would like a ESC%G to begin 
italic output mode. By using the printer driver all printers may be handled in a similar manner. 


There are two parts to the alphanumeric portion of the printer driver: the CommandTable 
data table and the DoSpecial() routine. 


Command Table 


The Command Table is used to convert all escape codes that can be handled by simple substi- 
tution. It has one entry per ANSI command supported by the printer driver. When you are 
creating a custom CommandTable, you must maintain the order of the commands in the 
same sequence as that shown in printer.h and printer.z. By placing the specific codes for your 
printer in the proper position, the conversion takes place automatically. 
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Note: If the code for your printer requires a decimal 0 (an ASCII NULL character), you enter 
this NULL into the Command Table as octal 376 (decimal 254). 


Placing an octal value of 377 (255 decimal) in a position in the command table indicates to the 
printer device that no simple conversion is available on this printer for this ANSI command. 
For example, if a printer does not support one of the functions (for instance, if a daisy-wheel 
printer does not have a foreign character set), 377 octal (255 decimal) is placed in that position. 
However, 377 in a position can also mean that the ANSI function is to be handled by code lo- 
cated in the DoSpecial() function. 


DoSpecial() Function 


The DoSpecial() function is meant to implement all the ANSI functions that cannot be done 
by simple substitution, but can be handled by a more complex sequence of control characters 
sent to the printer. These are functions that need parameter conversion, read values from 
Preferences, and so on. 


The DoSpecial() function is set up as follows: 


#include ”exec/types.h” 
#include ” devices/printer.h” 
#include ”devices/prtbase.h” 


extern struct PrinterData *PD; 


DoSpecial(command,outputBuffer,vline,currentVMlI,crlfFlag,Parms) 
char outputBuffer |]; 
UWORD *command; 
BYTE *vline; 
BYTE *currentVM]; 
BYTE *«crlfF lag; 
UBYTE Parms|]; 
{ /* code begins here... */ 


where 
command 
points to the command number. The devices/printer.h file contains the definitions for 


the routines to use (aRIN is initialize, and so on). 


vline 
points to the value for the current line position. 
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currentVMI 
points to the value for the current line spacing. 


crlfFlag 
points to the setting of the ‘‘add line feed after carriage return” flag. 


Parms 


contain whatever parameters were given with the ANSI command. 


outputBuffer 


points to the memory buffer into which the converted command is returned. 


Almost every printer will require an aRIN (initialize) command in DoSpecial(). This command 
reads the printer settings from Preferences and creates the proper control sequence for the 


specific printer. Also, it returns the character set to normal (not italicized, not bold, and so on). 
Other functions depend on the printer. 


Certain functions are implemented both in the CommandTable and in the DoSpecial() rou- 
tine. These are functions such as superscript, subscript, PLU (partial line up), and PLD (partial 
line down), which can often be handled by a simple conversion. However, certain of these func- 
tions must also adjust the printer device’s line-position variable. 
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Chapter 16 


Clipboard Device 


Introduction 


The clipboard device is implemented as an Exec-style device. It is responsible for caching data 
that has been “‘cut” and providing data to “paste” in an application. 
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Clipboard Commands 


The clipboard responds to the following system functions: 


OpenDevice() 
CloseDevice() 
BeginIO() 
SendIO() 
DolIO() 


Open the clipboard device 

Close the clipboard device 

Initiate clipboard I/O 

Initiate a command and return immediately 


The I/O commands and their implementations are as follows: 


CMD_INVALID 
CMD_READ 


CMD_WRITE 


CMD_UPDATE 


CMD_CLEAR 


CMD_STOP 
CMD_START 
CMD_FLUSH 
CBD_POST 


CMD_CLIPREADID 
CMD_CLIPWRITEID 
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Always an invalid command. 


Read data from the clipboard for a paste. io_Offset and 
io_ClipID must be set to zero for the first read of a paste 
sequence. An io_Actual that is less than the io_Length 
indicates that all the data has been read. After all the data 
has been read, a subsequent read must be performed (one whose 
io_Actual returns zero) to indicate to the clipboard device 

that all the data has been read. This allows random access of 
the clip while reading (provided only valid reads are performed). 


Write data to the clipboard as a cut. io Offset and 
io_ClipID must be set to zero for the first write of a cut 


sequence. An update command indicates that all the data has 
been written. 


Indicate that the data provided with a write command is 
complete and available for subsequent read/pastes. 


Clear any cut from this unit. Subsequent read/pastes will have 
no data available. 


Service no commands except invalid, start, flush. 
Resume command servicing. 
Abort all pending commands. 


Post the availability of clip data. io _ClipID must be set to 
zero, a Subsequent write of this data does not have io_ClipID 
set to zero as described above, but to the value in 10_ClipID. 


Return the io_ClipID of the current clip to read. 
Return the io_ClipID of the latest clip written. 


Clipboard Data 


Data on the clipboard resides in one of three places. When an application posts a cut, the data 
resides in that application’s private memory space. When an application writes to the clip- 
board, either of its own volition or in response to a message from the clipboard to satisfy a post, 
the data is copied to the clipboard, either to memory or to a special disk file. When the clip- 
board is not open, the data resides in the special disk file. 


Data on the clipboard is self-identifying. It must be a correct IFF (Interchange Format Files) 
file; the rest of this this section refers to IFF concepts. See the appendixes of the Amiga ROM 
Kernel Reference Manual: Exec for a complete description of IFF. If the top-level chunk is of 
type CAT or LIST with an identifier of CLIP, that indicates that the contained chunks are 
different representations of the same data, in decreasing order of preference on the part of the 
producer of the clip. Any other data is as defined elsewhere (probably a single representation of 
the cut data produced by an application). 


The clipboard tool, which is the application that allows a Workbench user to view a clip, under- 
stands only the text (FTXT) and graphics (ILBM) form types.. Applications using the clipboard 
to export data should include at least one of these types in a CLIP CAT so that their data can 
be represented on the clipboard in some form for user feedback. 


The clipboard device nonstandard I/O request is called an IOClipReq and looks like a stan- 
dard request except for the addition of the io_ClipID field, which is assigned by the device to 
identify clips. It must be set to zero by the application for a post or an initial write or read, 
but preserved for subsequent writes or reads. The same initialization must be performed for the 
io_ Offset field, but for different reasons. 


struct IOClipReq { 


struct Message io_Message; 


struct Device *io_Device; /* device node pointer */ 

struct Unit *io_Unit; /* unit (driver private)* / 

UWORD §io_Command; /* device command */ 

UBYTE io_Flags; /* including QUICK and SATISFY */ 
BYTE io_Error; /* error or warning num */ 

ULONG _io_Actual; /* number of bytes transferred */ 
ULONG io_Length; /* number of bytes requested * / 
SPTR io_Data; /* either clip stream or post port */ 
ULONG io_Offset; /* offset in clip stream */ 

LONG _io_ClipID; /* ordinal clip identifier */ 
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Clipboard Messages 


When an application performs a post, it must specify a message port for the clipboard to send a 
message to if it needs the application to satisfy the post with a write called the SatisfyMsg. 


struct SatisfyMsg { 
struct Message sm_Message; /* the length will be 6 */ 
UWORD sm_Unit; /* 0 for the primary clip unit */ 
LONG sm_ClipID; /* the clip identifier of the post */ 
} 


If the application wishes to determine if a post it has recently performed is still the current clip, 
it should check the io_ClipID found in the post request upon return with that returned by the 
CLIPREADID command. 


If an application has a pending post and wishes to determine if it should satisfy it (for example, 
before it exits), it should check the io_ClipID of the post I/O request with that of the 
CLIPWRITEID command. If the application receives a satisfy message from the clipboard 
device (format described below), it must immediately perform the write with the io_ClipID of 
the post. The satisfy message from the clipboard may be removed from the application message 
port by the clipboard device at any time (because it is re-used by the clipboard device). It is 
not dangerous to spuriously satisfy a post, however, because it is identified by the io_ClipID. 


The cut data is provided to the clipboard device via either a write or a post of the cut data. 
The write command accepts the data immediately and copies it onto the clipboard. The post 
command allows an application to inform the clipboard of a cut, but defers the write until the 
data is actually required for a paste. In the preceding discussion, references to the read and 
write commands of the clipboard device actually refer to a sequence of read or write commands, 
where the clip data is acquired and provided in pieces instead of all at once. The clipboard has 
an end-of-clip concept that is somewhat analogous to end-of-file for both read and write. The 
read end-of-file must be triggered by the user of the clipboard in order for the clipboard to move 
on to service other users’ requests, and consists of reading data past the end of file. The write 
end-of-file is indicated by use of the update command, which indicates to the clipboard that the 
previous write commands are completed See the description of the commands above for more 
information. 


Multiple Clips 


The clipboard also supports multiple clips. This is not to be confused with the multiple IFF 
CLIP chunks in a clip, which allow for different representation of the same data. Multiple clips 
store different data. Applications performing cut and paste operations generally specify the pri- 
mary clip. The alternate clips are provided to aid applications in the maintenance of a set of 
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clips (like a scrapbook). The multiple clips are implemented as different units in the clipboard 
device, and are thus accessed at open time: 


OpenDevice(‘‘clipboard.device’’, unit, &£IOClipRegq, 0); 


The primary clip unit used by applications to share data is unit 0; use of alternate clip units is 
by private convention. 


Example Program 


#include ”exec/types.h” 
#include ” graphics/gfx.h” 
#include ” graphics/gfxbase.h” 
#include ” graphics/view.h” 
#include ” intuition /intuition.h” 
#include ”libraries/dos.h” 
#include ” libraries/dosextens.h” 
#include ”devices/clipboard.h” 


extern int stdout; 
struct GfxBase *GfxBase; 


char buffer|80], *b, c; 
int rawConsole, oldStdout, postID; 


readS() 


{ 
b = buffer; 
while (Read(rawConsole, &c, 1), ((c != ’\34’) && (c != ’\r’))) { 
*b++ = ¢; 
printf(” %lc”, c); 
} 
tb = ’\0’; 
} 


main() 


{ 
int 1; 
GfxBase = (struct GfxBase *) OpenLibrary(” graphics.library” , 0); 


printf(” CBOpen returned %ld.\n”, CBOpen(PRIMARY_CLIP)); 
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printf(” CBOpen RAW: file is %olx.\n”, rawConsole = 
Open(” RAW:25/25/615/150/clipboard.device test”, MODE_OLDFILE)); 


oldStdout = stdout; 
stdout = rawConsole; 
printf(” \033[20h” ); 


c= 0; 

postID = 0; 

while (c != ’\34’) { 

while((postID) && (!WaitForChar(rawConsole, 1000000))) 
if (CBCheckSatisfy(&postID)) { 
if (postID) { 

printf(” Satisfy post data\n”); 
readS(); 
printf(” \nsatisfying \”%s\”\n”, buffer); 
CBSatisfy Post(bu ffer); 
postID = 0; 


} 


Read(rawConsole, &c, 1); 
switch (c) { 
case ’w’: 
printf(” Enter cut data\n”); 
readS(); 
printf(”\ncutting \”%s\”\n”, buffer); 
CBCutS(buffer); 
break; 
case ’r’: 
CBPasteS( buffer); 
printf(” paste is \”%s\” \n”); 
break; 
case ’p’: 
printf(” Posting post...\n” ); 
postID = CBPost(); 
break; 
default:; 


; 
j 


CBClose(); 
printf(” CBClose returned.\n”); 


Close(rawConsole); 
stdout = oldStdout; 
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printf(”\nTest Done.\n”); 


} 


strcpy( to, from ) 
register char *to, *from; 


{ 
do { 


*to++ = *from; 
\ while( *from+-+ ); 


strcat( to, from ) 
register char *to, *from; 


{ 


while( *to ) to++4; 


strepy( to, from }; 


} 


strlen( s ) 
register char *s; 


{ 


register 1 = 0; 
while( *s++ ) i++; 


return( 1 ); 


j 


stremp( a, b ) 
register char *a, *b; 
{ 
while( *a++ == *b ) { 
if( ! *b++ ) return( 0 


j 


if( *--a < *b ) return( -1 ); 
return( 1 ); 


F 


} 


char * 
index(s, c ) 
char *s, ¢c; 


{ 


char sc; 
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while( sc = *s ) { 


if( sc == c ) return(s ); 
Sr +; 
} 
return( 0 ); 
} 
char * 


rindex( origs, c ) 
char *origs, c; 


{ 


char sc, *s; 
s = origs|strlen( origs ) - 1]; 


while( s >= origs ) { 
if( *s == c ) return(s ); 


} 


char * 
TailPath( path ) 
char *path; 


{ 


char *last; 


/* looking for ” volume:/name/bar/tail” . 
* The routine breaks if volume has a slash... 


7 


/* check for a slash */ 
if( ! (last = rindex( path, ’/’ )) ) { 


/* no slash. Check for a colon */ 


if( ! (last = rindex( path, ’:’ )) ) { 


/* no colon either. Return the original */ 
return( path }; 


j 
j 


return( last ); 
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Support Functions Called from Example Program 


DORA BOOS OSC CIGO AGO II IISA / 
* Program name: cbio 

* Purpose: Provide standard clipboard device interface routines 

* such as Open, Post, Read, Write, etc. 
PORES GIA OI ICAI Ta OC IAI / 
#include ”exec/types.h” 

#include ” exec/ports.h” 

#include ”exec/io.h” 

#include ” devices /clipboard.h” 


struct [OClipReq clipboardIO = 0; 
struct MsgPort clipboardMsgPort = 0; 
struct MsgPort satisfyMsgPort = 0; 


int CBOpen(unit) 
int unit; 
{ 


int error; 


/* open the clipboard device */ 
if ((error = OpenDevice(”clipboard.device”, unit, &clipboardIO, 0)) != 0) 
return(error); 


/* Set up the message port in the I/O request */ 
clipboardMsgPort.mp_Node.In_Type = NT_MSGPORT; 
clipboardMsgPort.mp_Flags = 0; 

clipboardMsgPort.mp_SigBit = AllocSignal(-1); 
clipboardMsgPort.mp_SigTask = (struct Task *) FindTask((char *) NULL); 
AddPort( &clipboardMsgPort); 

clipboardIO.io_Message.mn_ReplyPort = &clipboardMsgPort; 


satisfy MsgPort.mp_Node.In_Type = NT_MSGPORT; 

satisfy MsgPort.mp_Flags — 0; 

satisfyMsgPort.mp_SigBit = AllocSignal(-1); 

satisfyMsgPort.mp_SigTask = (struct Task *) FindTask((char *) NULL); 
AddPort( &satisfy MsgP ort); 


return(0); 


} 


CBClose() 


RemPort(&satisfyMsgPort); 
RemPort(&clipboardMsgPort); 
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CloseDevice( &clipboardIO); 
j 


CBCut(stream, length) 

char *stream; 

int length; 

{ 
chpboardIO.io_Command = CMD_WRITE; 
chpboardIlO.io_Data = stream; 
clipboardIO.io_Length = length; 
clipboardIO.io_Offset = 0; 
clipboardIO.io_ClipID = 0; 
DolO(&clipboardIO); 
clipboardIO.i10_Command =-CMD_UPDATE; 
DolO(&clipboard!IO); 


j 


writeLong(Idata) 

LONG +*ldata; 

{ 
clipboardIO.i10_Command = CMD_WRITE; 
clipboardlO.i0_Data = ldata; 
chpboardIO.io_Length = 4; 
DolO(&clipboardIO); 

} 


CBSatisfyPost(string) 
char *string; 


{ 
int length; 
char *s; 
length = 0; 
Ss = string; 


while(*s++) length++; 
chpboardIO.10_Offset = 0; 


writeLong(” FORM” ): /* >FORM” */ 
length += 12; 

writeLong(&length); [* # */ 
writeLong(” TEST” ); /* °TEST” */ 
writeLong(” TEST”); /* TEST” */ 
length -=— 12; 

writeLong(&length); /* # */ 


clipboardIO.10_Command = CMD_WRITE; 
clipboardlO.io_Data = string; 
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} 


chpboardIO.io_Length = length; 
DolO(&clipboardIO); 


chpboardIO.io_Command = CMD_UPDATE; 


DolO(&clipboardIO); 


CBCutS(string) 


char *string; 


} 


clipboardIO.i0o_ClipID = 0; 
CBSatisfy Post(string); 


CBPasteS(string) 


char *string; 


{ 


} 


int 


int length; 


clipboardIO.io_Command = CMD_READ; 
clipboardIO.1i0_Data = 0; 
chipboardIO.io_Length = 16; 
chipboardIO.i0_Offset = 0; 
chipboardIO.i0_ClipID = 0; 
DolO(&clipboardIO); 


clipboardIlO.io_Command = CMD_READ; 
clipboardlO.io_Data = &length; 
clipboardIO.io_Length = 4; 
DolO(&clipboardIO); 


chpboardIO.10_Command = CMD_READ; 
chpboardIO.10_Data = string; 
clipboardIO.io_Length = length; 
DolO(&clipboardIO); 


string|length| = ’\0’; 


/* force end of file to terminate read */ 
clipboardIO.io_Command = CMD_READ; 
clipboardIlO.io_Length = 1; 
clipboardIO.i0o_Data = 0; 
DolO(&clipboardIO); 


CBPost() 


{ 


/* text string */ 
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clipboardIO.io_Command = CBD_POST; 
clipboardIO.io_Data = &satisfyMsgPort; 
clipboardIO.io_ClipID = 0; 
DolO(&clipboardIO); 
return(clipboardIO.io_ClipID); 

} 


int 


CBCurrentReadID() 


clipboardIO.io_Command = CMD_CLIPREADID; 
DolO(&clipboardIO); 
return(clipboardIO.io_ClipID); 


} 


int 

CBCurrentWritelD() 

{ 
clipboardIO.io_Command = CMD_CLIPWRITEID; 
DolO(&clipboardIO); 
return(clipboardIO.io_ClipID); 


} 


BOOL 
CBCheckSatisfy(id Var) 
int *idVar; 


{ 


struct SatisfyMsg *sm; 


if (*idVar == 0) 
return(TRUE); 
if (*idVar < CBCurrentWriteID()) { 
*idVar = 0; 
return(TRUE); 
} 
if (sm = (struct SatisfyMsg *) GetMsg(&satisfyMsgPort)) { 
if (*idVar == sm->sm_ClipID) 
return(TRUE); 


return(FALSE); 
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PART ITI 


Chapter 17 


Math Functions 


This chapter describes the structure and calling sequences required to access the Motorola Fast 
Floating Point and IEEE Double Precision math libraries via the Amiga-supplied interfaces. 


Introduction 


In its present state, the FFP library consists of three separate entities: the basic math library, 
the transcendental math library, and C and assembly-language interfaces to the basic math 
library plus FFP conversion functions. The IEEE Double Precision library presently consists of 
one entity: the basic math hbrary. 
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FFP Floating Point Data Format 


FFP floating-point variables are defined within C by the float or FLOAT directive. In assembly 
language they are simply defined by a DC.L/DS.L statement. All FFP floating-point variables 
are defined as 32-bit entities (longwords) with the following format: 


MMMMMMMM MMMMMMMM MMMMMMMM SEBEEEEE 
31 23 15 7 


where 

M = 24-bit mantissa 

S = Sign of FFP number 

FE = Exponent in excess-64 notation 
The mantissa is considered to be a binary fixed-point fraction; except for 0, it is always normal- 
ized (has a 1 bit in its highest position). Thus, it represents a value of less than 1 but greater 
than or equal to 1/2. 
The sign bit is reset (0) for a positive value and set (1) for a negative value. 
The exponent is the power of two needed to correctly position the mantissa to reflect the 
number’s true arithmetic value. It is held in excess-64 notation, which means that the two’s- 
complement values are adjusted upward by 64, thus changing $40 (-64) through $3F (+63) to 


$00 through $7F. This facilitates comparisons among floating-point values. 


The value of 0 is defined as all 32 bits being Os. The sign, exponent, and mantissa are entirely 
cleared. Thus, Os are always treated as positive. 


The range allowed by this format is as follows: 
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DECIMAL: 


9.22337177 x 10**18 > +VALUE > _ 5.42101070 x 10**-20 


-9.22337177 x 10**18 < -VALUE <_ -2.71050535 x 10**-20 


BINARY (HEXADECIMAL): 


FRFFFFF x 2**63 > +VALUE > _ .800000 x 2**-63 


-FRFFFFF x 2**63 < -VALUE <_ -.800000 x 2**-64 


Remember that you cannot perform any arithmetic on these variables without using the fast 
floating-point libraries. The formats of the variables are incompatible with the arithmetic for- 


mat of C-generated code; hence, all floating-point operations are performed through function 
calls. 


FFP Basic Mathematics Library 


The FFP basic math library resides in ROM and is opened by making a call to the 
OpenLibrary() function with mathffp.library as the argument. In C, this might be imple- 
mented as shown below: 


int MathBase; 


main() 


{ 


char lib_name|] = ”mathffp.library” ; 


if ((MathBase = OpenLibrary(lib_name, 0)) < 1) { 
printf(”Can’t open %s: vector = %08x\n”, lib_name, 
MathBase); 


exit(); } 
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The global variable MathBase is used internally for all future library references. 


This library contains entries for the basic mathematics functions such as add, subtract, and so 
on. The C-called entry points are accessed via code generated by the C compiler when standard 
numerical operators are given within the source code. Note that to use either the C or assembly 
language interfaces to the basic math library all user code must be linked with the library 
amiga.ltb. The C entry points defined for the basic math functions are as follows: 


ffixi Convert FFP variable to integer 
Usage: il = (int) f1; 


fflti Convert integer variable to FFP 
Usage: f1 = (FLOAT) il; 


femp)i Compare two FFP variables 


Usage: if (f1 <> f2) {}; 


ftsti Test an FFP variable against zero 


Usage: if (!f1) {}; 


fabsi Take absolute value of FFP variable 
Usage: fl = abs(f2); 


fnegi Take two’s complement of FFP variable 


Usage: fl = -f2; 


faddi Add two FFP variables 
Usage: fl = f2 + f3; 


fsubi Subtract two FFP variables 
Usage: fl — f2 - f3; 


fmuli Multiply two FFP variables 
Usage: fl = f2 * f; 


fdivi Divide two FFP variables 
Usage: fl = f2 / f2; 


Be sure to include proper data type definitions as shown in the example below. 
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#include <libraries/mathffp.h> 
int MathBase; 


main() 
{ 
FLOAT f1, f2, f3; 
int il, i2, i3; 
char lib_name[] = ”mathffp.library”; 


if((MathBase = OpenLibrary(lib_name, 0)) < 1 ) { 
printf(” Can’t open %s: vector = %08x\n”, lib_name, 
MathBase); 


exit(); } 


il = (int) f1; /* Call ffixi entry */ 
fi == (FLOAT) il; /* Call fflti entry */ 
if (f1 < f2) {}; /* Call fempi entry */ 
if (!f1) {}; /* Call ftsti entry */ 
fl = abs(f2); /* Call fabsi entry */ 
fl = -f2; /* Call fnegi entry */ 
fl = f2 + f3; /* Call faddi entry */ 
fl = f2 - f3; /* Call fsubi entry */ 
fl = f2 * f3; /* Call fmuli entry */ 
fl = f2 / f3; /* Call fdivi entry */ 


} 


The Amiga assembly language interface to the Motorola Fast Floating Point basic math rou- 
tines is shown below, including some details about how the system flags are affected by each 
operation. This interface resides in amiga.lib and must be linked with the user code. Note that 
the access mechanism from assembly language is as follows: 


MOVEA.L _MathBase,A6 
JSR _LVOSPFix,A6 
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_LVOSPFix - Convert FFP to integer 


Inputs: 
Outputs: 
Condition codes: 


_LVOSPFIt - Convert integer to FFP 


Inputs: 
Outputs: 
Condition codes: 


_LVOSPCmp- Compare 


Inputs: 


Outputs: 


Condition codes: 
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DO = FFP argument 

DO = Integer (two’s complement) result 
N = 1 if result is negative 

Z = 1 if result is zero 

V = 1if overflow occurred 

C = undefined 

X = undefined 


DO = Integer (two’s complement) argument 
DO = FFP result 

N = 1 if result is negative 

Z = 1 if result is zero 


V=0 
C = undefined 
X = undefined 


D1 = FFP argument 1 
DO = FFP argument 2 
DO = +1 if argl < arg2 
DO = -1 if argl > arg2 
DO = 0 if argl = arg2 


N = 0 

Z = 1 if result is zero 
V=0 

C = undefined 

X = undefined 


GT = arg2 > argl 
GE = arg2 >= argl 
EQ = arg2 = argl 
NE = arg2 <> argl 
LT = arg2 < argl 
LE = arg2 <= argl 


_LVOSPTst - 


_LVOSPAbs - 


_LVOSPNeg - 


Test 


Inputs: 
Outputs: 


Condition codes: 


D1 = FFP argument 

DO = +1 if arg > 0.0 

DO = -1 if arg < 0.0 

DO = 0 if arg = 0.0 

N = 1 if result is negative 
Z = 1 if result is zero 


V=0 
C = undefined 
X = undefined 


EQ = arg — 0.0 
NE = arg <> 0.0 
PL = arg >= 0.0 
MI = arg < 0.0 


Note: This routine trashes the 


argument in D1. 


Absolute value 


Inputs: 
Outputs: - 


Condition codes: 


Negate 


Inputs: 
Outputs: 
Condition codes: 


DO = FFP argument 
DO = FFP absolute value result 


N= 0 

Z = 1 if result is zero 
V=0 

C = undefined 

X = undefined 


DO = FFP argument 
DO = FFP negated result 
N = 1 if result is negative 
Z = 1 if result is zero 


V=0 
C = undefined 
X = undefined 
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_LVOSPAd4d - 


_LVOSPSub - 


_LVOSPMul - 


_LVOSP Dw - 


Addition 


Inputs: 


Outputs: 


Condition codes: 


Subtraction 


Inputs: 


Outputs: 


Condition codes: 


Multiply 


Inputs: 


Outputs: 


Condition codes: 


Divide 
Inputs: 


Outputs: 


Condition codes: 
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D1 = FFP argument 1 

DO = FFP argument 2 

DO = FFP addition of argl+arg2 result 
N = 1 if result is negative 

Z = 1 if result is zero 

V = 1 if result overflowed 

C = undefined 

Z = undefined 


D1 = FFP argument 1 

DO = FFP argument 2 

DO = FFP subtraction of arg2-arg1 result 
N = 1 if result is negative 

Z = 1 if result is zero 

V = 1 if result overflowed 

C = undefined 

Z = undefined 


DO = FFP argument 1 

D2 = FFP argument 2 

DO = FFP multiplication of argl*arg2 result 
N = 1 if result is negative 

Z = 1 if result is zero 

V = 1 if result overflowed 

C = undefined 

Z = undefined 


D1 = FFP argument 1 
DO = FFP argument 2 
DO = FFP division of arg2/arg1 result 
N = 1 if result is negative 
Z = 1 if result is zero 
V = 1 if result overflowed 
C = undefined 
= undefined 


FFP Transcendental Mathematics Library 


The FFP transcendental math library resides on disk and must be accessed in the same way as 
the basic math hbrary after it is loaded into system RAM. The name to be included in the 
OpenLibrary() call is mathtrans.library. In C, this might be implemented as follows: 


int MathBase; 
int MathTransBase; 


main() 


{ 
char bmath_namel|] = ”mathffp.library”; 
char tmath_name[] = ”mathtrans.library”; 


if((MathBase = OpenLibrary(bmath_name, 0)) < 1 ) { 
printf(” Can’t open %s: vector = %08x\n”, bmath_name, 
MathBase); 


exit(); } 


if((MathTransBase = OpenLibrary(tmath_name, 0)) < 1 ) { 


printf(” Can’t open %s: vector = %08x\n”, tmath_name, 
Math TransBase); 


exit(); } 


j 


The global variables MathBase and MathTransBase are used internally for all future library 
references. Note that the transcendental math library is dependent upon the basic math library 
and, therefore, is opened after the basic math library has been opened. 


This library contains entries for the transcendental math functions sine, cosine, and so on. The 
C-called entry points are accessed via code generated by the C compiler when the actual func- 


tion names are given within the source code. The C entry points defined for the transcendental 
math functions are as follows: 


SPAsin Return arcsine of FFP variable. 
Usage: f1 = SPAsin(f2); 


SPAcos Return arccosine of FFP variable. 


Usage: f1 = SPAcos(f2); 
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SPAtan Return arctangent of FFP variable. 
Usage: fl = SPAtan/(f2); 


SPSin Return sine of FFP variable. This function accepts an FFP radian argument 
and returns the trigonometric sine value. For extremely large arguments where 
little or no precision would result, the computation is aborted and the “‘V”’ con- 
dition code is set. A direct return to the caller is made. 


Usage: f1 — SPSin(f2); 


SPCos Return cosine of FFP variable. This function accepts an FFP radian argument 
and returns the trigonometric cosine value. For extremely large arguments 
where little or no precision would result, the computation is aborted and the 
‘““V”? condition code is set. A direct return to the caller is made. 


Usage: f1 = SPCos(f2); 


SPT an Return tangent of FFP variable. This function accepts an FFP radian argument 
and returns the trigonometric tangent value. For extremely large arguments 
where little or no precision would result, the computation is aborted and the 
‘““V” condition code is set. A direct return to the caller is made. 


Usage: f1 = SPTan(f2); 


SPSincos Return sine and cosine of FFP variable. This function accepts an FFP radian 
argument and returns both the trigonometric sine and cosine values. If both the 
sine and cosine are required for a single radian value of interest, this function 
will result in almost twice the execution speed of calling the sin and cos func- 
tions independently. For extremely large arguments where little or no precision 
would result, the computation is aborted and the “V”’ condition code is set. A 
direct return to the caller is made. 


Usage: f1 = SPSincos(&f3, f2); 


SPSinh Return hyperbolic sine of FFP variable. 
Usage: fl = SPSinh(f2); 


SPCosh Return hyperbolic cosine of FFP variable. 
Usage: f1 = SPCosh(f2); 


SPTanh Return hyperbolic tangent of FFP variable. 
Usage: f1 = SPTanh(f2); 


SPExp Return e to the FFP variable power. This function accepts an FFP argument 


and returns the result representing the value of e (2.71828...) raised to that 
power. 
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Usage: f1 = SPExp/(f2); 


SPLog Return natural log (base e) of FFP variable. 
Usage: f1 = SPLog(f2); 


SPLog10 Return naparian log (base 10) of FFP variable. 
Usage: f1 = SPLogl10(f2); 


SPPow Return FFP arg2 to FFP arg]. 
Usage: f1 — SPPow/(f3, f2); 


SPSart Return square root of FFP variable. 
Usage: f1 = SPSaqrt(f2); 


SPTieee Convert FFP variable to IEEE format 
Usage: il = SPTieee(f1); 


SPFieee Convert IEEE variable to FFP format. 
Usage: fl = SPFieee(il); 


Be sure to include proper data type definitions, as shown in the example below. 


#include <mathffp.h> 


int MathBase; 
int MathTransBase; 


main() 


{ 
FLOAT f1, f2, £3; 


int il, i2, 13; 
char bmath_name|] = ”mathffp.library” ; 
char tmath_name|] = ”mathtrans.library” ; 


if((MathBase = OpenLibrary(bmath_name, 0)) < 1 ) { 
printf(” Can’t open %s: vector = %08x\n”, bmath_name, MathBase); 


exit(); } 


if((MathTransBase = OpenLibrary(tmath_name, 0)) < 1 ) { 
printf(”Can’t open %s: vector = %08x\n”, tmath_name, MathTransBase); 


exit(); } 
fl = SPAsin(f2); /* Call SPAsin entry */ 
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fl = SPAcos(f2); 
fl = SPAtan(f2); 


fl = SPSin(f2); 
fl = SPCos(f2); 
fl = SPTan(f2); 
fl = SPSincos(&f3, f2); 


fl = SPSinh(f2); 
fl = SPCosh(f2); 
f1 = SPTanh(f2); 


fl = SPExp/(f2); 
fl = SPLog(f2); 
fl = SPLog10(f2); 
fl = SPPow/(f2); 


fl = SPSaqrt/(f2); 
il = SPTieee(f2); 
f1 = SPFieee(il1); 
} 


/* Call SPAcos entry */ 
/* Call SPAtan entry */ 


/* Call SPSin entry */ 

/* Call SPCos entry */ 
/* Call SPTan entry */ 
/* Call SPSincos entry */ 


/* Call SPSinh entry */ 
/* Call SPCosh entry */ 
/* Call SPTanh entry */ 


/* Call SPExp entry */ 
/* Call SPLog entry */ 
/* Call SPLog10 entry */ 
/* Call SPPow entry */ 
/* Call SPSqrt entry */ 


/* Call SPTieee entry */ 
/* Call SPFieee entry */ 


The section below describes the Amiga assembly language interface to the Motorola Fast Float- 
ing Point transcendental math routines and includes some details about how the system flags 
are affected by the operation. Again, this interface resides in the library file mathlink.lib and 
must be linked with the user code. Note that the access mechanism from assembly language is 
as shown below: 


LEA _LVOSPAsin,A6 
JSR  _MathTransBase(A6) 
_LVOSP Asin - Arcsine 
Inputs: DO = FFP argument 
Outputs: DO = FFP arctangent radian result 
Condition codes: Ne==0 
Z = 1 if result is zero 
VY = 0 
C = undefined 
X = undefined 
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_LVOSPAcos - 


_LVOSPAtan - 


_LVOSPSin - 


_LVOSP Cos - 


Arccosine 


Inputs: 
Outputs: 


Condition codes: 


Arctangent 


Inputs: 
Outputs: 


Condition codes: 


Sine 


Inputs: 
Outputs: 


Condition codes: 


Cosine 


Inputs: 
Outputs: 


Condition codes: 


DO = FFP argument 
DO = FFP arctangent radian result 


N= 0 

Z = 1 if result is zero 
V=0 

C = undefined 

X = undefined 


DO = FFP argument 
DO = FFP arctangent radian result 


N = 0 

Z = 1 if result is zero 
V = 0 

C = undefined 

X = undefined 


DO = FFP argument in radians 
DO = FFP sine result 

N = 1 if result is negative 

Z = 1 if result is zero 

V = 1 if result is meaningless 
(that is, input magnitude too large) 
C = undefined 

X = undefined 


DO = FFP argument in radian 

DO = FFP cosine result 

N = 1 if result is negative 

Z = 1 if result is zero 

V = 1 if result is meaningless 
(that is, input magnitude too large) 
C = undefined 

X = undefined 
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_LVOSPTan - Tangent 


Inputs: 
Outputs: 
Condition codes: 


_LVOSPSincos - Sine and cosine 


Inputs: 
Outputs: 


Condition codes: 


_LVOSPSinh- — Hyperbolic sine 


Inputs: 
Outputs: 
Condition codes: 


_LVOSPCosh - —_Hyperbolic cosine 


Inputs: 
Outputs: 
Condition codes: 


466 Math Functions 


DO = FFP argument in radians 
DO = FFP tangent result 

N = 1 if result is negative 

Z = 1 if result is zero 

V = 1 if result is meaningless 
(that is, input magnitude too large) 
C = undefined 

X = undefined 


DO = FFP argument in radians 

D1 = Address to store cosine result 
DO = FFP sine result 

(D1) = FFP cosine result 

N = 1 if result is negative 

Z = 1 if result is zero 

V = 1 if result is meaningless 

(that is, input magnitude too large) 
C = undefined 

X = undefined 


DO = FFP argument in radians 
DO = FFP hyperbolic sine result 
N = 1 if result is negative 

Z = 1 if result is zero 

V = 1 if overflow occurred 

C = undefined 

X = undefined 


DO = FFP argument in radians 
DO = FFP hyperbolic cosine result 
N = 1 if result is negative 

Z = 1 if result is zero 

V = 1 if overflow occurred 

C = undefined 

X = undefined 


_LVOSPTanh - 


_LVOSPExp - 


_LVOSPLog - 


_LVOSPLog10 - 


Hyperbolic tangent 


Inputs: 
Outputs: 
Condition codes: 


Exponential 


Inputs: 
Outputs: 
Condition codes: 


Natural logarithm 


Inputs: 
Outputs: 
Condition codes: 


Naparian (base 10) logarithm 


Inputs: 
Outputs: 
Condition codes: 


DO = FFP argument in radians 

DO = FFP hyperbolic tangent result 
N = 1 if result is negative 

Z = 1 if result is zero 

V = 1 if overflow occurred 

C = undefined 

X = undefined 


DO = FFP argument 

DO = FFP exponential result 
N=0 

Z = 1 if result is zero 

V = 1 if overflow occurred 
C = undefined 

Z = undefined 


DO = FFP argument 

DO = FFP natural logarithm result 
N = 1 if result is negative 

Z = 1 if result is zero 

V = 1 if argument negative or zero 
C = undefined 

Z = undefined 


DO = FFP argument 

DO = FFP natural logarithm result 
N = 1 if result is negative 

Z = 1 if result is zero 

V = 1 if argument negative or zero 


C = undefined 
Z = undefined 
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_LVOSPPow - 


_LVOSPSart - 


_LVOSPTieee - 


_LVOSPFieee - 


Power 


Inputs: 


Outputs: 
Condition codes: 


Square root 


Inputs: 
Outputs: 
Condition codes: 


Convert to IEEE format 


Inputs: 
Outputs: 
Condition codes: 


Convert from IEEE format 


Inputs: 
Outputs: 
Condition codes: 
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D1 = FFP argument value 

DO = FFP exponent value 

DO = FFP result of arg taken to exp power 
N =0 

Z = 1 if result is zero 

V = 1 if result overflowed or arg < 0 

C = undefined 

Z = undefined 


DO = FFP argument 

DO = FFP square root result 

N = 0 

Z = 1 if result is zero 

V = 1if argument was negative 
C = undefined 

Z = undefined 


DO = FFP format argument 

DO = IEEE floating-point format result 
N = 1 if result is negative 

Z = 1 if result is zero 


V = undefined 
C = undefined 
Z = undefined 


DO = IEEE floating-point format argument 
DO = FFP format result 

N = undefined 

Z = 1 if result is zero 

V = 1if result overflowed FFP format 

C = undefined 

Z = undefined 


FFP Mathematics Conversion Library 


The FFP mathematics conversion library is accessed by linking code into the executable file 
being created. The name of the file to include in the library description of the link command 
line is mathlink_lib.lib. When this is included, direct calls are made to the conversion functions. 
Only a C interface exists for the conversion functions; there is no assembly language interface. 


The basic math library is required in order to access these functions and might be opened as 
shown below. 


int MathBase; 
main() 
char bmath_name|] = ”mathffp.library”; 
if ((MathBase = OpenLibrary(bmath_name, 0)) < 1 ) { 


printf(” Can’t open %s: vector = %08x\n”, bmath_name, 
MathBase); 


exit(); } 


} 
The global variable MathBase is used internally for all future basic math library references. 
This lhbrary contains entries for the conversion functions associated with math library usage. 
The C-called entry points are accessed via code generated by the C compiler when the actual 


function names are given within the source code. The C entry points defined for the math 
conversion functions are as follows: 


afp Convert ASCII string into FFP equivalent. 
Usage: fnum = afp(&string(0}); 


fpa Convert FFP variable into ASCII equivalent. 
Usage: exp = fpa(fnum, &string|0]); 


arnd Round ASCII representation of FFP number. 
Usage: arnd(place, exp, &string|0]); 
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dbf 


fpbed 


Be sure to include proper data type definitions, as shown in the example below. Print state- 
ments have been included to help clarify the format of the math conversion function calls. 


Convert FFP dual-binary number to FFP equivalent. 
Usage: fnum = dbf(exp, mant); 


Convert FFP variable to BCD equivalent. 
Usage: fpbcd(fnum, &string(0}); 


#include <mathffp.h> 


char st1[80] = ”3.1415926535897” ; 
char st2|80] = ”2.718281828459045” ; 
char st3|80], st4[80]; 


int MathBase; 


main() 


{ 


FLOAT numl, num2, num3, num4, num5, num6, num7, num8, num9; 


FLOAT nl, n2, n3, n4, nd, n6, n7, n8, n9; 

int il, 12, 13, 14, 15, 16, 17, 18, 19; 

int expl, exp2, exp3, exp4, mantl, mantz2, 
mant3, mant4, placel, place2; 


if ((MathBase=OpenLibrary(” mathffp. library” ,0)) < 1) { 


printf{(”Can’t open mathffp.library:vector =%08x\n”, 


MathBase); 
exit(); 
} 
nl = afp(st1); /* Call afp entry */ 
n2 = afp(st2); /* Call afp entry */ 
printf(”\n\nASCII %s converts to floating point %f”, 
stl, n1); 
printf(”\nASCII %s converts to floating point %f”, 
st2, n2); 


numl = 3.1415926535897; 
num2 = 2.718281828459045; 


expl = fpa(numl, st3); /* Call fpa entry */ 
exp2 = fpa(num?2, st4); /* Call fpa entry */ 


printf(” \n\nfloating point %f converts to ASCII %s”, num1, st3); 
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printf(” \nfloating point %f converts to ASCII %s”, 


num2, st4); 
placel = -2; 
place2 = -1; 
arnd(placel, exp1, st3); /* Call arnd entry */ 
arnd(place2, exp2, st4); /* Call arnd entry */ 


printf(”\nASCII round of %f to %d places yields %s”, 
numl, placel, st3); 

printf(”\nASCII round of %f to %d places yields %s”, 
num2, place2, st4); 


expl —-3; exp2 — 3; exp3 =—-3; exp4 = 3; 
mantl = 12345; mant2 = -54321; mant3 = -12345:; 
t4 = 594321; 


nl = dbf(exp1, mantl1); /* Call dbf entry */ 

n2 = dbf(exp2, mantz2); /* Call dbf entry */ 

n3 = dbf(exp3, mants3); /* Call dbf entry */ 

n4 = dbf(exp4, mant4); /* Call dbf entry */ 

printf(”\n\ndbf of exp = %d and mant = %d yields FFP number 
of %f”, expl, mantl, nl); 

printf(” \ndbf of exp = %d and mant = %d yields FFP number 
of %f”, exp2, mant2, n2); 

printf(”\ndbf of exp = %d and mant = %d yields FFP number 
of %f”, exp3, mant3, n3); 

printf(”\ndbf of exp = %d and mant = %d yields FFP number 
of %f”, exp4, mant4, n4); 

num] — -numl; 

fpbed(numl1, st3); /* Call fpbed entry */ 

st3|8] = ’\0’; 

strcepy(&12, &st3/4}): 

st3/4| = ’\0’; 


strepy(&il, st3); 
printf(” \n\nfloating point %f converts to BCD %08x% 08x”, num1, i1, i2); 
num2 = -num?2; 
fpbcd(num?2, st4); /* Call fpbed entry */ 
st4|8| = ’\0’; 
strepy(&i4, &st4[4]); 
st4|4] = °\0’; 
strepy(&i3, st4); 
printf(”\nfloating point %f converts to BCD 
% 08x% 08x”, num2, i, 14); 
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IEEE Double-precision Basic Math Library 


The IEEE double-precision basic math lhbrary resides on disk and is opened by making a call to 
the OpenLibrary() function with mathieeedoubbas.library as the argument. In C, this 
might be implemented as shown below. 


int MathIeeeDoubBasBase; 
main() 
char lib_name[] = ”mathieeedoubbas.library” ; 


if ((MathIeeeDoubBasBase = OpenLibrary(lib_name, 0)) < 1 ) { 
printf(” Can’t open %s: vector = %08x\n”, lib_name, 
MathIeeeDoubBasBase); 


exit(); } 


j 


The global variable MathIeeeDoubBasBase is used internally for all future library references. 


This library contains entries for the basic mathematics functions, such as add, subtract, and so 
on. The C-called entry points are accessed via code generated by the C compiler when the 
actual function names are given within the source code. The C entry points defined for the 
IEEE double-precision basic math functions are listed below: 


IEEEDPF ix 
Convert IEEE double-precision variable to integer 


Usage: il = IEEEDPFix(f1); 
IEFEEDPF It 
Convert integer variable to IEEE double precision 


Usage: fl = IEEEDPFIt(i1); 


IEEEDPCmp 


Compare two IEEE double-precision variables 


Usage: — switch (IEEEDPCmp/(f1, f2)) {}; 


IEEEDPTst 
Test an IEEE double-precision variable against zero 
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Usage: switch (IEEEDPTst(f1)) {}; 


IEEEDPAbs 
Take absolute value of IEEE double-precision variable 


Usage: fl = IEEEDPAbs(f2); 


IEEEDPNeg 


Take two’s complement of IEEE double-precision variable 


Usage: f1 = IEEEDPNeg(f2); 


IEEEDPAdd 
Add two IEEE double-precision variables 


Usage: fl = JEEEDPAdd(f2, f3); 


IEEEDPSub 
Subtract two IEEEDPSub variables 


Usage: fl — IEEEDPSub/(f2, 3); 


IEEEDPMul 
Multiply two IEEE double-precision variables 


Usage: f1 = IEEEDPMul(f2, f3); 


IEEEDPDiv 
Divide two IEEE double-precision variables 


Usage: fl = IEEEDPDiv(f2, f3); 


Be sure to include proper data type definitions, as shown in the example below. 


int MathIeeeDoubBasBase; 


main() 


{ 
double fl, f2, f3; 


int il, 12, 13; 
char lib_name|| = ”mathieeedoubbas.library” ; 
if((MathIeeeDoubBasBase = OpenLibrary(lib_name, 0)) < 1 ) { 


printf(”Can’t open %s: vector = %08x\n”, lib_name, 
MathIeeeDoubBasBase); 


exit(); } 


il = IEEEDPFix(f1); /* Call IEEEDPFix entry */ 
fi = IEEEDPFIt(i1); /* Call IEEEDPFIt entry «/ 
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switch (IEEEDPCmp(f1, f2)) {}; 
switch (IEEEDPTst(f1)) {}; 

fl = JIEEEDPAbs(f2); 

fl = IEEEDPNeg(f2); 

fl = IEFEEDPAdd(f2, f3); 

fl = IEEEDPSub(f2, f3); 

fl = IEEEDPMul(f2, f3); 

fl = IEEEDPDiv(f2, f3); 


j 


/* Call TIEEEDPCmp entry */ 
/* Call IEEEDPTst entry */ 
/* Call IEEEDPAbs entry */ 
/* Call TIEEEDPNeg entry */ 
/* Call IEEEDPAdd entry */ 
/* Call TIEEEDPSub entry */ 
/* Call TEEEDPMul entry */ 
/* Call IEEEDPDiv entry */ 


The Amiga assembly language interface to the IEEE double-precision floating-point basic math 
routines is shown below, including some details about how the system flags are affected by each 
operation. Note that the access mechanism from assembly language is as shown below: 


LEA _LVOIEEEDPFix,A6 
JSR  _MathIeeeDoubBasBase(A6) 


_LVOIEEEDPFix - Convert IEEE double-precision to integer 
Inputs: DO/D1 = IEEE double-precision argument 
Outputs: DO = Integer (two’s complement) result 
Condition codes: N = 1 if result is negative 


Z = 1 if result is zero 
V = 11if overflow occurred 


C = undefined 
X = undefined 
_LVOIEEEDPFIet - Convert integer to IEEE double-precision 

Inputs: DO = Integer (two’s complement) argument 
Outputs: DO/D1 = IEEE double-precision result 
Condition codes: N = 1 if result is negative 

Z = 1 if result is zero 

V=0 

C = undefined 

X = undefined 
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_LVOIEEEDPCmp - 


_LVOIEEEDPTst - 


Compare two IEEE double-precision values 


Inputs: DO/D1 = IEEE double-precision argument 1 
D2/D3 = IEEE double-precision argument 2 
Outputs: DO = +1 if argl < arg2 


DO = -1 if argl > arg2 
DO = Oif arg] = arg2 


Condition codes: N=0 
Z = 1 if result is zero 
¥=0 
C = undefined 
X = undefined 


GT = arg2 > argl 
GE = arg2 >= argl 
EQ = arg2 — argl 
NE = arg2 <> argl 
LT = arg2 < argl 
LE = arg2 <= argl 


Test an IEEE double-precision value against zero 


Inputs: DO/D1 = IEEE double-precision argument 
Outputs: DO = +1 if arg > 0.0 

DO = -1 if arg < 0.0 

DO = 0 if arg = 0.0 


Condition codes: N = 1 if result is negative 
Z = 1 if result is zero 
V=0 
C = undefined 
X = undefined 


EQ = arg = 0.0 
NE = arg <> 0.0 
PL = arg >= 0.0 
MI = arg < 0.0 
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_LVOIEEEDPAbs - 


_LVOIEEEDPNeg - 


_LVOIEEEDPAdd - 
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Absolute value 


Inputs: 
Outputs: 


Condition codes: 


Negate 


Inputs: 
Outputs: 


Condition codes: 


Addition 
Inputs: 


Outputs: 


Condition codes: 


DO/D1 = IEEE double-precision argument 
DO/D1 = IEEE double-precision absolute 


value result 


N =0 
= 1 if result is zero 
Ve e=0 
C = undefined 
X = undefined 


DO/D1 = IEEE double-precision argument 
DO/D1 = IEEE double-precision negated result 
N = 1 if result is negative 

Z = 1 if result is zero 


V=0 
C = undefined 
X = undefined 


DO/D1 = IEEE double-precision argument 1 

D2/D3 = IEEE double-precision argument 2 

DO/D1 = IEEE double-precision addition of 
argl+arg2 result 

N = 1 if result is negative 

Z = 1 if result is zero 

V = 1 if result overflowed 

C = undefined 

Z = undefined 


_LVOIEEEDPSub - 


_LVOIEEEDPMul - 


_LVOIEEEDPDyw - 


Subtraction 
Inputs: 


Outputs: 


Condition codes: 


Multiply 
Inputs: 


Outputs: 


Condition codes: 


Divide 
Inputs: 


Outputs: 


Condition codes: 


DO/D1 = IEEE double-precision argument 1 

D2/D3 = IEEE double-precision argument 2 

DO/D1 = IEEE double-precision subtraction 
of argl-arg2 result 

N = 1 if result is negative 

Z = 1 if result is zero 

V = 1if result overflowed 

C = undefined 

Z = undefined 


DO/D1 = IEEE double-precision argument 1 

D2/D3 = IEEE double-precision argument 2 

DO/D1 = IEEE double-precision multiplication 
of argl*arg2 result 

N = 1 if result is negative 

Z = 1 if result is zero 

V = 1 if result overflowed 

C = undefined 

Z = undefined 


DO/D1 = IEEE double-precision argument 1 
D2/D3 = IEEE double-precision argument 2 
DO/D1 = IEEE double-precision division 
of argl/arg2 result 
N = 1if result is negative 
Z = 1 if result is zero 
V = 1if result overflowed 
C = undefined 
Z = undefined 
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Chapter 18 


Workbench 


This chapter shows how to use the Workbench facilities in your applications. For information 
about Iconfd, the icon editor for making Workbench icons, see the appendixes of the Introduc- 
tion to Amiga manual for revision 1.1 of the system software. 


Introduction 


Workbench is both an application program and a screen in which other applications can run. 
Workbench allows users to interact with the Amiga file system by using icons, and it gives the 


programmer access to a body of library functions for manipulating the application’s objects and 
icons. 


Workbench 479 


Here are definitions of some terms that may be unfamiliar or used in unfamiliar ways in this 
chapter. 


Workbench object 
A Workbench object contains all the information that Workbench needs to display and 
use a project, tool, drawer, etc. The two kinds of Workbench objects are WBObject 
(as Workbench uses objects) and DiskObject (as most other users will view objects in 
memory or in a file on disk). 


wcon 
This is a shorthand name for a Workbench object. An icon may be in memory or on 


disk or both. 


info file 
The disk representation of an icon. The format of an icon on disk is slightly different 
from an icon in memory, but one is obtainable from the other. 


strings 
A null-terminated sequence of bytes. 


activating 


The act of starting a tool, opening a drawer, and so on. The term opening is reserved 
for windows and files. 


tool 
An application program or system utility. 


project 
Something produced by an executable program and associated with an executable pro- 


gram, for example, a text file or a drawing. 


drawer 
A disk-based directory. 


The Icon Library 


The icon library, tcon.library, has memory-management routines, icon input and output rou- 
tines, and string manipulation routines. The “Library Summaries” appendix to this manual 
contains the reference pages for this library. 
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The Info File 


The info file is the center of interaction between applications and Workbench. This file stores 
all the necessary information to display an icon and to start up an application. An info file can 
contain several different types of icons, as shown in table 17-1. 


Table 18-1: Contents of a Workbench Info File 


Icon Name Object 
WBDISK The root of a disk 
WBDRAWER A directory on the disk 
WBTOOL A directly runnable program 


WBPROJECT _ A data file of some sort 
WBGARBAGE _ The trash can directory 
WBKICK A non-DOS disk 


The actual data present in the info file depends on the icon type. Note that any graphical 
image can be used for any icon type in the info file. In fact, the graphical image need not be 
unique for each type of icon. However, it is strongly recommended as a matter of programming 
style that each type of icon have a unique graphical image associated with it. In fact, you may 
want to have several unique images associated with an icon type. For example, you can have 
several different images associated with the WBTOOL type of icon info file. 


Most people will not access the info file directly. The icon manipulation library does all the 
work needed to read and write info files. The GetDiskObject(), PutDiskObject(), and 
FreeDiskObject() routines are especially helpful. The calling sequence of each of these is 
given in the icon library reference pages in the “Library Summaries” appendix. 


THE DISKOBJECT STRUCTURE 


The DiskObject structure is at the beginning of all info files, and is used in the routines 
GetDiskObject(), PutDiskObject(), and FreeDiskObject(). The structure is defined in 


workbench/workbench.h and contains the following elements: 


do_Magic 
A magic number that the icon library looks for to make sure that the file it is reading 
really contains an icon. It should be the manifest constant WB_DISKMAGIC. 
PutDiskObject() will put this value in the structure, and GetDiskObject will not 
believe that a file is really an icon unless this value is correct. 
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do_Version 


This provides a way to enhance the info file in an upwardly-compatible way. It should 
be WB_DISKVERSION. The icon library will set this value for you and will not 


believe weird values. 


do_Gadget 


This contains all the imagery for the icon. See the ‘““Gadget Structure” section for more 
details. 


do_Type 
The type of the icon (WBTOOL, WBPROJECT, and so on). 


do_Default Tool 
Default tools are used for projects and disks. For projects the default tool is the pro- 
gram invoked when the project is activated. This tool may be absolute (DISK:file), 
relative to the root of this disk (:file), or relative to the project (file). If the icon is of 
type WBDISK, the default tool is the diskcopy program that will be used when this 
disk is the source of a copy. 


Note that if the tool is run via the default tool mechanism (for example, a project was 
activated, not a tool), all the information in the project’s info file is used, and the tool’s 


info file is ignored. This is especially important for variables like StackSize and 
ToolWindow. 


do_ToolTypes 


ToolTypes is an array of free-format strings. Workbench does not enforce any rules 
on these strings, but they are useful for passing environment information. See the 
‘“ToolTy pes” section for more information. 


do_CurrentX, do_Current Y 
Drawers have a virtual coordinate system. The user can scroll around in this system 
using the scroll gadgets on the “drawers”? window. Each icon in the drawer has a posi- 
tion in the coordinate system. CurrentX and CurrentY contain the icon’s current 
position in the drawer. 


do_DrawerData 
If the icon is capable of being opened as a drawer (WBDISK, WBDRAWER, WBGAR- 
BAGE), it needs a DrawerData structure to go with it. This structure contains an 
Intuition NewWindow structure. (see Amiga Intuition Reference Manual for more 
information about windows.) Workbench uses this to hold the current window position 
and size of the window so it will reopen in the same place. The CurrentX and 
CurrentyY of the origin of the window is also stored. 


do_ToolWindow 
By default, Workbench will start a program without a window. If ToolWindow is set, 
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this file will be opened and made the standard input and output of the program. This 
window will also be put into the process’s pr_WindowPtr variable and will be used 
for all system requesters. Note that this work is actually done in the language- 
dependent start-up script; if you are coding in assembly language or an unsupported 
language, you will have to do the work yourself. The only two files that it makes sense 
to open are CON: or RAW:. See the AmigaDOS manuals for the full syntax accepted 
by these devices. 


do_StackSize 


This is the size of the stack used for running the tool. If this is null, then Workbench 
will use a reasonable default stack size (currently 4K bytes). 


THE GADGET STRUCTURE 


To hold the icon’s image, Workbench uses an Intuition Gadget structure, defined in 
intuition/intuition.h or intuition/intuition.i for the assembly language version. Workbench res- 
tricts some of the values of the gadget. Any unused field should be set to 0. For clarity in 
presentation, you can use the assembly language version of these structures, 


Note: The C version has the leading “gg_” stripped off. (Workbench structure members have 
the same name in all languages supported by Amiga). The Intuition gadget structure members 
that Workbench pays attention to are listed below: 


gg_ Width 
This is the width (in pixels) of the active icon’s active region. Any mouse button press 
within this range will be interpreted as having selected this icon. 


gg_ Height 
The same as Width, only in the vertical direction. 


gg Flags 

Currently the gadget must be of type GADGIMAGE. Three highlight modes are 
supported: GADGHCOMP, GADGHIMAGE, and GADGBACKFILL. GADGHCOMP 
complements the image specified (as opposed to Intuition, which complements the select 
box). GADGHIMAGE uses an alternate selection image. GADGBACKFILL is similar 
to GADGHCOMP, but ensures that there is no ‘‘orange ring” around the selected 
image. It does this by first complementing the image, and then flooding all orange pix- 
els that are on the border of the image to blue. (In case you do not use the default 
colors, orange is color 3 and blue is color 0.) All other flag bits should be 0. 


gg_Activation 
The activation should have only RELVERIFY and GADGIMMEDIATE set. 
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gg_Type 
The gadget type should be BOOLGADGET. 


gg _GadgetRender 
Set this to an appropriate Image structure. 


gg SelectRender 
Set this if and only if the highlight mode is GADGHIMAGE. 


The Image structure is typically the same size as the gadget, except that ig_ Height is often 
one pixel less than the gadget height. This allows a blank line between the icon image and the 
icon name. The image depth must be 2; ig _PlanePick must be 3; and ig PlaneOnOff should 
be 0. The ig NextImage field should be null. 


ICONS WITH NO POSITION 


Picking a position for a newly created icon can be tricky. NO_ICON_POSITION is a magic 
value for do_CurrentX and do_CurrentyY that instructs Workbench to pick a reasonable 
place for the icon. Workbench will place the icon in an unused region of the drawer. If there is 
no space in the drawers window, the icon will be placed just to the right of the visible region. 


Workbench Environment 


When a user activates a tool or project, Workbench runs a program. This program is a 
separate process and runs asynchronously to Workbench. This allows the user to take advan- 
tage of the multiprocessing features of the Amiga. 


The environment for a tool under the Workbench is quite different from the environment when 
a tool is run from the CLI. The CLI does not create a new process for a program; it jumps to 
the program’s code and the program shares the process with the CLI. This means that the pro- 
gram has access to all the CLI’s environment, but the program must be very careful to restore 
all the correct defaults before returning. Workbench starts a tool from scratch and explicitly 
passes the environment to the tool. 


One of the things that a Workbench program must set up is stdin and stdout. By default, a 
Workbench program does not have a window to which its output will go. Therefore, stdin and 


stdout do not point to legal file handles. If your program attempts to printf(), it will destroy 
the system. 
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START-UP MESSAGE 


Right after the tool is started, Workbench sends the tool a message, which is posted to the mes- 


sage port in the tool’s process. This message contains the environment and the arguments for 
the tool. 


Each icon that is selected in the Workbench is passed to the tool. The first argument is the tool 
itself. If the tool was derived from a default tool, then this is passed in addition to the project. 


All other arguments are passed in the order in which the user selected them; the first icon 
selected will be first. 


The tool may do what it wishes with the start-up message; however, it must deallocate the mes- 
sage sooner or later. If the message is replied to Workbench, then Workbench will take care of 
all the clean-up. The tool should not do this until it finishes executing, because part of the 
clean-up is freeing the tool’s data space. 


The start-up message, whose structure is outlined in workbench/startup.h, has the following 
structure elements: 


sm_Message 
A standard Exec message. The reply port is set to the Workbench. 


sm_Process 
The process descriptor for the tool (as returned by CreateProcess()) 


sm_Segment 
The loaded code for the tool (returned by LoadSeg()) 


sm_NumArgs 
The number of arguments in sm_ArgList 


sm_ToolWindow 
This is the same string as the DiskObject’s do_ToolWindow. It is passed here so 
the tool’s start-up code can open a window for the tool. If it is null, no default window 
is opened. 


sm_ArgList 
This is the argument list itself. 


Each argument has two parts. The wa_Name element is the name of the argument. If this 1s 
not a default tool or a drawer-like object, this will be the same as the string displayed under the 
icon. A default tool will have the text of the do_DefaultTool pointer; a drawer will have a 
null name passed. The wa_Lock is always a lock on a directory, or is NULL (if that object 
type does not support locks). 
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The following code fragment will work for all arguments (assuming that open will work on them 


at all). 


LockArg( arg ) 
struct WBArg *arg; 
int openmode; 


{ 


} 


LONG olddir; 
LONG lock; 


/* see if this type can be locked */ 

if( arg- >wa_Lock == NULL ) { 
/* cannot lock it -- it must be a device (for example, DFO:) */ 
return( NULL ); 


} 


/* change directory to where the argument is * / 
olddir = CurrentDir( arg- >wa_Lock ); 


/* open the argument up */ 
lock = Lock( arg->wa_Name, SHARED_LOCK ); 
if( lock === NULL ) { 
/* who knows: maybe the user canceled a disk insertion 
* request. The real reason can be gotten by IoErr() 
* 
/ 
return( NULL ); 
j 


/* set the directory back */ 
CurrentDir( olddir ); 


return( lock ); 


For more routines to manipulate Workbench arguments, see the function appendix. 


THE STANDARD START-UP CODE 


The standard start-up code handles the worst of the detail work of interfacing with the system. 
The C start-up code (startup.obj) waits for the start-up message, opens the tool window (if 
one has been requested), sets up SysBase and DOSBase, and passes the start-up message on 


to main(). When main() returns (or exit() is called) it replies the message back to 
Workbench. 
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The main() procedure is called with two parameters: argv and arge. If arge is not NULL, 
you have been called from the CLI. If arge is NULL, you have been called from Workbench. 
The global variable WBenchMsg points to the Workbench start-up message. 


Note: A word of warning for those of you who do not use the standard start-up 
sequence: you must turn off task switching (with Forbid()) before replying the message to 
Workbench. This will prevent Workbench from unloading your code before you can tell the 
DOS that you want to exit. See the C start-up code in the “Example Programs” section. 


The ToolTypes Array 


This section shows how the ToolTypes array should be formatted, and describes the standard 
entries in the ToolTypes array. In brief, ToolTypes is an array of strings. These strings can 
be used to encode information about the icon that will be available to all who wish to use it. 
The formats are user-definable and user-extensible. 


Workbench does not enforce much about the ToolTypes array, but some conventions are 
strongly encouraged. A string may be up to 32K bytes large, but you should not make it over a 
line long. The alphabet is 8-bit ANSI (for example, normal ASCII with foreign-language exten- 
sions). To see what it looks like, try typing with the Alt key held down. Avoid special or non- 
printing characters. The case of the characters is significant. The general format is 


<name >= <value>||<value>|* 


where <name> is the field name and <value> is the text to associate with that name. If the 
ID has multiple values, the values may separated by a vertical bar. Currently, the value should 
be the name of the application that understands this file. For example, a basic program might 


be 


FILETYPE=ABasiC. program| text 


This notifies the world that this file is acceptable to either a program that is expecting any arbi- 


trary type of text (for example, an editor) or to a program that only understands a basic 
program. 


Two routines are provided to help you deal with the Tooltype array. FindToolType() 
returns the value of a Tooltype element. Using the above example, if you are looking for 
FILETYPE, the string ‘““ABasiC.program| text” will be returned. 
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Match ToolValue() returns nonzero if the specified string is in the reference value string. This 
routine knows how to parse vertical bars. For example, using the reference value string of 
‘“ABasiC.program|text”, MatchToolValue() will return TRUE for “text” and 
“ABasiC.program”’ and FALSE for everything else. 


Example Programs 


Some example programs, including a start-up sequence, are provided in the following sections. 


FRIENDLYTOOL 


This program tells the application if it can understand a particular object. 


/* INPUTS 


* — diskobj -- a workbench DiskObject (a returned by GetDisk Object) 
* id -- the application identifier 
*k 


* OUTPUTS 


* nonzero if it understands this object’s type 


“) 


#-include ” exec/types.h” 
#include ” workbench /workbench.h” 


#include ” workbench /icon.h” 
LONG IconBase; 


FriendlyTool( diskobj, id ) 
struct DiskObject *diskob}; 
char *id; 
{ 

char **toolarray; 

char *value; 


/* default return value is failure */ 
int isfriendly = 0; 


/* this assumes that you have not already opened the icon library 
* elsewhere in your program. You undoubtedly have, because 
* you managed to get a DiskObject structure. 


+) 
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IconBase = OpenLibrary( ICONNAME, 1 ); 
if( IconBase == NULL ) { 

/* couldn’t find the library??? */ 

return( 0 ): 


/* extract the tool type value array */ 
toolarray = diskobj->do_ToolType; 


/* find the FILETYPE entry */ 
value = FindToolType( toolarray, ”FILETYPE” ); 
if( value ) { 

/* info file did define the FILETYPE entry */ 


isfriendly = MatchToolValue( value, id ); 
} 


Close( IconBase ); 


/* protect ourselves from inadvertent use */ 
IconBase = -1; 


return( isfriendly ); 


START-UP PROGRAM 


EK 2K 2 2K ee 2K 2K 2 ke Eo 2 2k 2 2k 2K 2 2k eco 2K 2 2 ek 2K 2 2 2c 2 2 2 2K 2k cK 2K 2 2c 2K 2 2K 2 2 2 2c og 2K 2k 2c ie og 2K 2K IE 2K 2 2k 2K 2K 2K ok 
* 

* C Program Startup/Exit (Combo Version: CLI and WorkBench) 

* 


OOO OR ORK dG dak RG a i kK ak ak ak ok ak 2k ak ok ak ak ak ok 
RAK AA [Included Files 22222 I aR aK a 2k ak 


INCLUDE ”exec/types.i” 
INCLUDE ” exec/alerts.1” 
INCLUDE ” exec /nodes.1” 
INCLUDE ” exec /lists.i” 
INCLUDE ” exec/ports.i” 
INCLUDE ” exec /libraries.i” 
INCLUDE ” exec/tasks.1” 
INCLUDE ” libraries/dos.1” 
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INCLUDE ” libraries/dosextens.1” 
INCLUDE ” workbench/startup.1” 


2K 2 2k KE 2k Imported 2 2 ke ee 2 2k oo 2 2 fe oe 2 2k 2 KF 2c ak 2 2 ie ae 2c ke 2k 2 2 fee ok 2 2c 2g 2k ae ok 2c kc ie 2k 2c ok kc aK afc oe 2k EK 2k 2k 2k ok 


xlib macro 
xref _LVOI1 
endm 


xref  _AbsExecBase 
xref _Input 
xref _Output 


xref _main - C code entry point 


xhib Alert 

xlib FindTask 
xlib Forbid 

xlib GetMsg 

xhb OpenLibrary 
xlib CloseLibrary 
xlib ReplyMsg 
xlib Wait 

xhb WaitPort 


xhb CurrentDir 
xlib Open 


2K OK 2 2K OK 2k Exported AE EE He ie he te 2 2 2 2k 2 2k 2 2k KK OK 2K IK OK OK ee ek ok 2K oe 2 kc 2k 2k 2 2 2 IK a 2K 2 2 2c ke oe 2 2K kK 2K ok 


xdef _SysBase 
xdef _DOSBase 


xdef _errno 
xdef _stdin 
xdef _stdout 
xdef _stderr 


xdef _exit - standard C exit function 
xdef _WBenchMsg 


callsys macro 
CALLLIB _LVOI1 
endm 


490 Workbench 


7K KKK OK kK a ok kK ok a kok ak ok 2k ok ok a ok ak 2 ok ak ok ake 2 ok ke 2k ok ok ok ok og ok ok fe 2k 2 oe oc ok 2 ok a 2 2 ok 2k ok fe 2c oe ok 2k 


* 

* Standard Program Entry Point 
* 

* main (arge, argv) 

* int argc; 

x char *argv||; 

xk 


2Fe 2 2c 2 2 2K Ko 2c fe 2c 2 2 2 2k ok te 2k 2 KK oe a ke 2 2 2 ok ke ok 2k a ok kc fe 2 oe fe 2c 2 2 oe oe kc 2k 2 2 ec 2k 2 2K oe gk 2 2 2 2K 2K i 2 oo Kk Ok 


startup: - reference for Wack users 
move.] sp,initialSP ; initial task stack pointer 
move.| d0,dosCmdLen 
move.| a0,dosCmdBuf 


clr.] _WBenchMsg 

fenenn= get Exxec’s library base pointer: 
move.| _AbsExecBase,a6 
move.| a6,_SysBase 


a get the address of our task 


suba.] al,al 
callsys FindTask 
move.] d0,a4 


peonnnn are we running as a son of Workbench? 
tst.] pr_CLI(A4) 
beq from Workbench 


joooeo- attempt to open DOS library: 
bsr openDOS 


Senna == find command name: 
move.] pr_CLI(a4),a0 


add. a0,a0 ‘ bcp] pointer conversion 
add. a0,a0 

move.| cli_CommandName(a0),a0 

add. a0,a0 ; bep] pointer conversion 
add.1| a0,a0 


jona--- create buffer and array: 
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2$: 
1$: 


3$: 


4$: 


5$: 


63: 


parmExit: 
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link 
movem.| 
lea 

lea 
move.| 
moveq.| 


a6,#-(100+16*4+2*4) 
d2/a2/a3,-(sp) 
argvBuffer,a2 
argvArray,a3 
a3,16(sp) 
#1 ,d2 


; save 
; param counter 


fetch command name: 


moveq.| 
move.b 
move.| 
bra.s 
move.b 
dbf 
clr.b 


#0,d0 
(a0)+,d0 
a2,(a3)+ 
1$ 
(a0)+,(a2)+ 
d0,2$ 

(a2)+ 


; size of command name 
; ptr to command name 


collect parameters: 


move.| 
move.] 


dosCmdLen,d0 
dosCmdBuf,a0 


skip control characters and space: 


move.b 
subq.] 
ble.s 
cmp.b 
ble.s 


(a0)+,d1 
#1,d0 
parmExit 
#? dl 
3$ 


copy parameter: 


addq.| 
move.] 
bra.s 
move.b 
subq.] 
cmp.b 
ble.s 
move.b 
bra.s 


clr.b 
bra.s 
clr.b 
clr.] 


move.| 
movem.| 


#4142 
a2,(a3)+ 
5$ 
(a0)+,d1 
#41 d0 
Hdl 
6$ 
d1,(a2)+ 
4$ 


(a2)+ 
3$ 

(a2)+ 
(a3)+ 


d2,d0 
(sp)+,d2/a2/a3 


pea argvArray 
move.| d0,-(sp) 


* ‘The above code relies on the end of line containing a control 
* character of any type, 1.e. a valid character must not be the 


* last. This fact is ensured by DOS. 


? 


get standard input handle: 
jsr _Input 
move.| dO,_ stdin 


get standard output handle: 


jsr Output 
move.| d0O,_stdout 
move.| dO,_stderr 


call C main entry point 
jsr _main 


return success code: 

moveq.| #0,D0 

move.| initialSP sp ; restore stack ptr 
rts 


from Workbench: 


open the DOS library: 
bsr openDOS 


we are now set up. wait for a message from our starter 
bsr waitmsg 


save the message so we can return it later 
move.] d0,_ WBenchMsg 


push the message on the stack for wbmain 
move.| d0,-(SP) 
elr.] -(SP) indicate: run from Workbench 


get the first argument 
move.| d0,a2 
move.| sm_ArgList(a2),d0 
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docons: 


domain: 


beq.s docons 


and set the current directory to the same directory 


move.| _DOSBase,a6 
move.| d0,a0 

move.| wa_Lock(a0),d1 
callsys CurrentDir 


get the toolwindow argument 
move.] sm_ToolWindow(A2),d1 
beq.s domain 


open up the file 
move.] #MODE_OLDFILE,d2 
callsys Open 


set the C input and output descriptors 


move.] d0,_stdin 
move.| d0,_stdout 
move.| dO,_stderr 
beq.s domain 


set the console task (so Open( ”*”, mode ) will work 
waitmsg has left the task pointer in A4 for us 

Is].] #:2,d0 

move.] d0,a0 

move.| fh_T ype(a0), pr_ConsoleTask(A4) 


jsr _main 
moveq. #0,d0 Successful return code 
bra.s exit2 


AE AE 2 2c EE 2 2K 2 2K 2 2 2K KK OK 2 Kk 2 kk 2 2 2 2 2 2 2 2 2 2 2 2K 2 ee 2k 2k ak ee 2 2k 2 2 2K KE aK oe 2 2c 2c 2k 2c eK EE KK 2K OK OK 


* + FF %% ¥ 


C Program Exit Function 


Warning: this function really needs to do more than this. 


eof 2 2 oe 2c 2 2c 2 2k 2c 2 2 2 oo ke fe 2 aE a oe 2k 2k 2 2 oe kc 2k oe og oc ic af 2 2 ok ic ofc 2 oc ke oe 2 of 2 2 ok of fe 2k 2 2c ke 2 2k 2 2 2 ok 2K 2K 2 2 2 fe ie 2c 2 2 2 2k 


_exit: 
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move.| A(SP),dO__; extract return code 


exit2: 
move.| initialSP,SP ; restore stack pointer 
move.] d0,-(SP)  ; save return code 


fennnne close DOS library: 


move.| _AbsExecBase,A6 
move.| _DOSBase,d0 
beq.s 1$ 
move.] d0,al 

1$: callsys CloseLibrary 


jannnne if we ran from CLI, skip workbench cleanup: 
tst.] _WBenchMsg 
beq.s exitToDOS 


peeeee return the startup message to our parent 
we forbid so workbench can’t UnLoadSeg() us 
before we are done: 

callsys Forbid 

move.] _WBenchMsg,al 

callsys ReplyMsg 


‘ann on- this rts sends us back to DOS: 
exit ToDOS: 
move. (SP)+,d0 
rts 


ALERT (AG_OpenLib!AO_DOSLib) 
moveq.l #100,d0 
bra.s ex1t2 


; This routine gets the message that workbench will send to us 
‘ called with task id in A4 


waitmsg: 
lea pr_MsgPort(A4),aO —-* our process base 
callsys WaitPort 
lea pr_MsgPort(A4),a0 = * our process base 
callsys GetMsg 
rts 
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; Open the DOS hbrary: 


openDOS 
clr.] _DOSBase 
lea DOSName,Al 
move.] #LIBRARY_VERSION,d0 
callsys OpenLibrary 
move.] DO, _DOSBase 
beq noDOS 


rts 
SOO OR OR OR OO Ro ok gk kok kk ok 
DATA 


KK 2K 2K 2K 2 2 KE 2K 2K 2 ke 2 2K 2K 2 2k oe 2K 2 2 2c oe 2k 2 2K oc oc ke > 2 2 2 2 2k kc oc ac oi 2 og a oo 2K 2K ok 2 2c oi 2c 2k ok 2 2c 2k ok 2 2k 2k og oo 2 2k ok 2K 2 2k ok 


VerRev dc.w 1,0 
_SysBase de.l O 
_DOSBase de.l O 
_errno de.l O 
_stdin de.l -l 
_stdout de.l -1 
_stderr de.l -1 
initialSP | de.l O 


_WBenchMsg_ dc.l O 


dosCmdLen de.l O 
dosCmdBuf dce.l O 


argvArray ds.l 32 

argvBuffer ds.b 256 

DOSName DOSNAME 
END 
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ECHO.C 


The following example program prints out arguments passed by the CLI or the WorkBench. 
/* Note: If WB startup, uses window opened by LStartup.obj */ 


#include <exec/types.h > 

#-include <workbench/startup.h> 
#include <lattice/stdio.h > 

extern struct WBStartup *WBenchMsg; 


main(arge,argv) 
int argc; 
char **argv; 
{ 
BYTE c; 
if(arge >0) { 
printCliArgs(argce,argv); 
} 


else { 
printWBArgs(WBenchMsg); 
while ((c=getchar()) != ’\n’); 


} 


printCliArgs(argce,argv ) 
int argc; 
char **argv; 
t A . 
int 15 
for(i=0; i<arge; 14+) { 
printf(” Arg %2ld = %s\n”,i,argv(i]); 
} 


} 
print WBArgs(msg) 
struct WBStartup *msg; 


{ 


struct WBArg *arg; 
int 1; 
for(i=0, arg—msg->sm_ArgList; i < msg->sm_NumArgs; it++,arg++) { 
printf(” WBArg%2ld:Lock =0x%06lx:Name=%s\n”, 
i,arg- >wa_Lock,arg- > wa_Name); 


printf(?7 PRESS <RET> TO EXIT \n’); 
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Appendix A 


Library Summaries 


This appendix contains UNIX-like summaries for the routines that are built into the Amiga 


ROM (or kickstart) software, as well as summaries of routines in disk-loadable libraries. The 
debug library documentation is included here as well. 


These documentation files are organized alphabetically. Following this introduction is a listing 
of each routine in this appendix, followed by the name of the library in which the routine is 
located. The tutorial sections of this manual show you how these routines relate to one another 
and give you the prerequisites for calling them. 


Most routines are listed as part of a library of routines. Before you can use a routine within 
your program, you must make sure that the library is opened. Opening libraries is explained 
fully in the “Libraries”? chapter of Amiga ROM Kernel Reference Manual: Exec but it bears 
repeating here. You open a library by using the OpenLibrary() function as follows: 


struct LibBase *LibBase; 


LibBase = OpenLibrary(” library.name” ,version); 
where 


library.name 
is a string that describes the name of the library you wish to open. 


version 


is the version number of the library that you wish to have opened. A value of O says 
give me any version. A value of 31, for example (which is the latest version as of this 


writing) means specifically to open version 31 of this library or a later version if 31 is 
not available. 


If the library is disk-resident, it is loaded and initialized. The OpenLibrary() function returns 
the address of the library base, which you must assign to a specific variable. In this way your 
program links into the library-specific interface code that is contained in amiga. lib. 


The names of the libraries that are currently part of the Amiga software and the corresponding 
names of the library base pointers associated with them are as follows: 


Library Name Library Base Pointer Name 
exec. library ExecBase 
clist. library ClistBase 
graphics. library GfxBase 
layers. library LayersBase 
intuition. library IntuitionBase 
mathffp. library MathBase 
mathtrans.library MathTransBase 
mathieeedoubbas.library MathIeeeDoubBasBase 
dos.library DosBase 
translator.library TranslatorBase 
icon. library IconBase 
diskfont.library DiskfontBase 
ramlib. library --- (not useful to C language) 


For example: 


#include ” graphics/gfx.h” 

struct GfxBase *GfxBase; 

GfxBase = OpenLibrary(” graphics. library” ,0); 

if(GfxBase === NULL) exit(NO_GRAPHICS_LIBRARY_FOUND); 


Note: If your program is coming up through the normal start-up code (see the ‘“‘Workbench”’ 


chapter), ezec.library and dos.library are already opened for you. Thus you need not open them 
yourself. 


The logic of this code is as follows: 


1. When calling a routine, C takes the parameters for the routine and pushes them onto 
the stack. For example: 


x = Routine(parmA, parmB); 


Then it calls a routine named ‘‘_Routine” (adds an underscore to the head of the rou- 
tine name). 


2. The underlying ROM (or disk-based) code usually expects its parameters to be passed 
in registers rather than on the stack. This is to make the code truly general-purpose 
(that is, it does not impose a particular stack frame) and more efficient for assembly 
language coding. 


Therefore, the interface code at _Routine, in turn, saves the contents of registers the 
routine will use, pulls parameters off the stack, jams them into registers, and finally 
passes control directly to the actual starting location of the routine itself. 


The linker needs the library base location because it is through a “jump-with-offset”’ 
from a machine register that the _Routine entry point is found. The Amiga uses a 
relocating loader in AmigaDOS, so you can never be sure exactly where a library of rou- 
tines is located. However, once the system has loaded a library, it knows how and 
where to find it and gives you a way to use the library’s routines. 


The following shows typical interface code linked to your program from amiga.lib: 


xref _LibBase ‘library base name is defined in 
-user’s file, this code gets linked 
‘to user’s program; get the value 
‘from there when library is opened. 
xdef _Routine 
‘make _Routine name external, 
‘visible to linker. 


_Routine: 
move.] A6,-(sp) ‘save register(s) 
move.] 8(sp),A0/Al1 ‘copy params A and B to regs. 
move.] _LibBase,A6 ‘load library base address 
jsr _LVORoutine(A6) ‘go to real routine 
move.| (sp)+,A6 ‘restore registers 
rts 


where _LVORoutine is a value representing the offset, within the library, at which the ‘‘real”’ 
routine (the routine that expects parameters in registers) is located. 


When you have finished using a library, at the end of your program, you should close it, using 
the CloseLibrary() function as follows: 


CloseLibrary(LibBase); 


If the system is running out of memory and needs to free up space, it can check the library- 
accessors field for various libraries. For those whose accessors value is zero, it can retrieve the 
memory that the library had used. 
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Appendix B 


Device Summaries 


This appendix contains UNIX-like summaries for the commands that may be applied to ROM- 
resident (or Kickstart-resident) devices, as well as summaries of routines in disk-loadable dev- 
ices. These documentation files are organized by device. Following this introduction is a listing 
of each command, followed by the library in which it is located. Note that there are no sum- 


maries for the trackdisk device; see the ‘“Trackdisk Device” chapter for information about this 
device. 


The tutorial sections of this manual give you information about how these device commands 
relate to each other and the prerequisites for calling them. To use any of the device commands, 
you must first open the device. The correct calling sequence for opening each device is shown in 
the device tutorial chapter itself. This introduction lists the names of the current set of devices 


that are included with the system. 


If the device is disk-resident, it is loaded and initialized. The OpenDevice() call fills in the 
io_Device and io_Unit fields of your I/O request block, thereby tying that request block to a 
specific device. When you say DoIO(IORequest), the DoIO() routine, among others, looks in 
the IORequest to find out which device is to be used. This prevents your needing to have a 
complete (duplicate) set of I/O transmit and control functions for each device. 


The following is a list of the names of the devices that are currently a part of the Amiga 
software. All of these are to be treated as null-terminated strings, which are given to the 
OpenDevice() function. For example: 


error = OpenDevice(”keyboard.device” ,O,LORequest,0); 


See OpenDevice() in the ‘“‘Routine Summaries” appendix for the meaning of the various fields 
of this command. 


Device Names 


audio.device 
clipboard.device 
console.device 
gameport.device 
input.device 
keyboard.device 
narrator.device 
parallel.device 
printer.device 
serial.device 
timer.device 
trackdisk.device 


When you have finished using a device, at the end of your program you should close it, using 
the CloseDevice() function as follows: 


CloseDevice(IORequest); 


You must also free whatever memory you may have dedicated to device communication before 
your program ends. Note that you must make sure that the device has responded to all of your 


I/O requests by returning your IORequest blocks before you attempt to close the device or 
deallocate the memory. 


If the system is running out of memory and needs to free up space, it can check the accessors 
field for various devices. If you have closed the device, it decrements its accessors count. For 


those devices whose accessors value is zero, the system can retrieve the memory that the device 
was using. 


Certain devices—the timer and console devices—have routines associated with them. These 
devices can almost be treated as libraries. To access these routines, you must, as with a library, 
provide a value to a specific base variable name: 


Device Base Address Name 


timer TimerBase 
console ConsoleDevice 


To get this base address, you must open the device, then copy the io_Device field from your 
TORequest block as the base address for this “library” routine. Note that unlike when you are 
using libraries, you need not issue a CloseLibrary() command after using the device routines. 
The CloseDevice() function call is sufficient. 


An example showing how to obtain the base address for the timer device is shown in the “Timer 
Device’’ chapter in this manual. 


Contents 


AbortIO 
AbortIO 
AbortI10O 
AbortI0O 
AddHandler 
AddResetHandler 
AddadTime 
ALLOCATE 
AskCType 
AskTrigger 
background 
BeginIO 
BeginIO 
BeginIO 
BeginIO 
Break 
CDAskKeyMap 
CDAskKeyMap 
CDInputHandler 
CDInputHandler 
CDSetKeyMap 
CDSetKeyMap 
CLEAR 

Clear 

Clear 

Clear 

Clear 

Clear 

Clear 

Clear 

Close 

Close 

Close 

Close 
CloseDevice 
CmpTime 
CurrentReadID 
CurrentWriteID 
DumpRPort 
Expunge 
Expunge 
FINISH 

FLUSH 

Flush 

Flush 

Flush 

Flush 

FREE 
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LOCK 
Open 
Open 
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Open 
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OpenDevice 
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serial. 


narrator. 
parallel. 


input. 


keyboard. 
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serial. 
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audio. 


Printer. 


audio 
input 
serial 


gameport 
narrator 
parallel 
clipboard 


audio 


device 
device 
device 
device 
device 
device 
device 
device 
device 
device 


.device 
.device 
.device 
.device 


device 
device 
device 
device 
device 
device 


.device 
.device 
.device 
.device 


device 
device 
device 
device 
device 


.device 


device 
device 
device 
device 
device 
device 
device 


.device 
.device 


device 
device 
device 
device 
device 
device 
device 
device 
device 
device 
.device 
.device 
.device 
.device 
.device 
.device 
.device 
.device 


OpenDevice 
OpenDevice 
PERVOL 

Post 
PrtCommand 
Query 

Query 
RawKeyConvert 
RawKeyConvert 
RawwWrite 

READ 

Read 

Read 

Read 

Read 

Read 

Read 
ReadEvent 
ReadEvent 
ReadMatrix 
RemHandler 
RemResetHandler 
RESET 

Reset 

Reset 

Reset 

Reset 

Reset 

Reset 

Reset 
ResetHandlerDone 
SetCType 
SetMPort 
SetMTrig 
SetMType 
SetParams 
SetParams 
SetPeriod 
SETPREC 
SetThresh 
SetTrigger 
START 

Start 

Start 

Start 

Start 

Start 

STOP 

Stop 

Stop 

Stop 

SubTime 
TR_ADDREQUEST 
TR_GETSYSTIME 
TR_SETSYSTIME 
UPDATE 

Update 
WALTCYCLE 
WRITE 

Write 


console. 
console. 
audio. 
clipboard. 
printer. 
serial. 
parallel. 
console. 
console. 
printer. 
audio. 
serial. 
console. 
console. 
narrator. 
parallel. 
clipboard. 
gameport. 
keyboard. 
keyboard. 
input. 
keyboard. 


audio 


parallel 


clipboard 


keyboard 


serial 


device 
device 
device 
device 
device 
device 
device 
device 
device 
device 
device 
device 
device 
device 
device 
device 
device 
device 
device 
device 
device 
device 


.aevice 
input. 
serial. 
printer. 
keyboard. 
narrator. 


device 
device 
device 
device 
device 


.device 
.device 
.device 
gameport. 
input. 
input. 
input. 


device 
device 
device 
device 


.device 
parallel. 
input. 
audio. 
input. 
gameport. 
audio. 
input. 
serial. 
printer. 
narrator. 
parallel. 
audio. 
serial. 
printer. 
parallel. 
timer. 
timer. 
timer. 
timer. 
audio. 
clipboard. 
audio. 
audio. 
serial. 


device 
device 
device 
device 
device 
device 
device 
device 
device 
device 
device 
device 
device 
device 
device 
device 
device 
device 
device 
device 
device 
device 
device 
device 


Write 
Write 
Write 
Write 
Write 
Write 
WriteEvent 


console. 
console. 
printer. 
narrator. 
parallel. 
clipboard. 
input. 


device 
device 
device 
device 
device 
device 
device 


qIoqe Oo} pueURoo oy} ACJ YSoenbey O/I ey} OF AaquTod —— ysoenbeyot 


SLAdNI 


‘poqzoge sem OJ 3eYy} UCTIeOTpUT Ue sUTezUOD ysenbeyot 
au} JO PTeaT] AOIIG OT ayy /TNJsseoons st Poqy ey} JI “[n}Jsseoonsun 


aq 0} peMOTTe ST FI 


‘pueullod aoTAep e WIOGe 0} SeTI} OIWoqQY 


NOILONNA 
TW 
‘ (ysenbexyoT ) o1 oq 
SISdONAS 


pueulod soOTASp eB YIOGe — OT WoqyY 
GWYN 


OIMoqy/sa0Taap “otpne 


aoTAsquadO/soTaap ° 
“oTpne 
“oTpne 
“oTpne 


ebundxq/a0Taep 
BOTASGESOTD/a0 TASp 
GLIYM GWO/OluUtTbeg/e0Taep 


qLWadn CAWO/OLUtTbed/e0TAap ' 
“oTpne 


dOLS ANO/olUTbeg/s0TAep 


LYWLS ANO/OlUTHed/a0TAap * 


LaSaY GWO/oluTbeg/a0TAap" 
“OoTpne 
“otpne 
“oTpne 
“oTpne 
“oTpne 
“oTpne 
“otpne 
“otpne 
“oTpne 
“OTpne 
“oTpne 


away dWO/OlUTbeg/s0Taap 

HSN1Td ANO/OLUTbDed/e0 TAep 
YWITO AWO/OlUTbe”g/a0TAap 
AFIOAOLIVM ANodv/olutbeg/eotaep 
OgudLAS AWodv/OlUTbed/e0TAep 
TOAUAd GNOdv/OlUTHbed/e0 Taep 
WOOT GNodv/oluUTbeg/a0TAap 
qgdd GNodv/olutbeq/a0Taep 
HSINIA GWOdv/OlUTbe_g/a0Taap 
ALWOOTTY GWOdv/olutbeg/e0TAap 
OlUTbeg/a0Taep 


OI Moqy/aoTaep’ 


otpne 


otTpne 


oTpne 
otpne 


otpne 


$juU937U0D 


aouapsceid ay} 3eS IO poeyzeooTTe aa,noA sToeuueyo ayy YOOT TeyjTe ysnu 
nok ‘szaystHhert aerempzey otTpne 9ey} 0F ATOSATp a103S OF epToep NOA FI 


“apoo 
qdnizejzut ut ALWOOTIW GWOdW esn jou og ‘uTehe wey} esn 0} SeTI} Tesn 
JOuICJ oy} usyM (NOILWOOTIVON YYHOI) TOTS ue UIN}eT SspueUROD sdOTASpP 
otpne [Te ‘/UeTORS ere sTeuUeYyo JI “peyusTUTJ ST UOT ReDOTTe 3YyR ToeqRye 
ysonber O/I ay setT[dez pue bet} yotnb oyuy szeaTo At os ‘/snouozyoudAse 
ST UOT}EOOTTR ay} ‘/OSTMIEYIO /ATREaTO ST (MOINO AOI) HeTJ yotnb 
auy Jt (ytogATdey uu) ATuO set{Tdez ALWOOTTW GWodW ‘eased TeyjTe ul 
“Jes st beT}J 4rem—ou dy pue STTe}J uOoT}eOOTTe ayy JT 
Io ‘uaTo js 
aq O} STeuUeYo PeYOOT OU eTe aay, pue Spadsdons UOTReOOTTe 2YyA JT 
‘snouortyoudAs St gLYOOTIV CWOdv 


‘Aay onbtun pue mou 
e So}eToueb WT /asTMreyjo ‘Ady owes Jey YIM SazeoOTTe ALWOOTTIW CAWOdv 
‘Kay uotT}eooTTe OTezZz—UOCU & YIM pozeoOTTe o1e SsTouUeYO FI 


-ysoenbert O/I ey} JO PTEeTF Frun sy ojUT dew 4Iq TeuueYyo oyy satdoo 
pue ‘sToeuueyo 
pezeooTTe ey} JO Yoes OAUT aoUSpedei1d UOT ReDOTTe ayy SaTdoo 
S[TouueYyoO pazeoOTTe 3y3 JO yoea ojuT Ady UuOTReOOTTe ayy SaTdoo 
‘ol8Z ST 3T JT /(AeyooTIW eot) AdY uOoTJeOOCTTe mou e SajeTEUeb 
‘sTeuueyo peqeooTTe oy} (LaSaY GW) sjesez 
?ALWOOTIW GNOdW ‘peyooTun ere sToeuueyo pa jZeooT[Te ey [Te UeYyM ~~ peer 
oq 0} SToeuUReYO peYOOT oYyy TOF HhuTATeM ASTT e UT ASsenber O/T uoT}eOOTTe 
au} seoetTd 41 ueyL *(NATIOLSTISNNVHO YNSOIGW) roIzZe ue YyyATM ysenbe7 
O/I YOoT ayy (HswATdey) set[der ‘os JT pue (YOOT GNodW) peYooT are 
s[Teuueyo Aue JT syooyo ALWOOTIW GWOdW ‘[njJsseoons sT uOoT eDOTTe eyYyy FI 


‘Saeouepesceid ,SsTeuueyo ayy SIAMOT 

JAIdLAS GNOdY TO sTeuueYyoO seeTy Aaya GWOdY Teaouseym uTebe a jeooTTe oF 
SOTT} 3#eYUQ ASTI e& UT AYSeNnber O/I ayQ saoetd 3T ‘ATeaToO ST HeTJ 3TeM_ou 
oud JI ‘*(ASTIWAOOTIW YNHOI) TOIZe ue pue (Tun OT) Ysenber O/I ey jo 
PTET} 3Iun ayA UT OTEZ e SUIN}eET ALWOOTTW GWOodW jes ST (.LIWMON dJOIGW) 
BeTyJ 3TeM—ou oy} pure uoTRZeUTqUIOD TeUUeYyoO AUe azeDOTTL OF STTe}F FT FI 


‘(Tid UT) soUepede1d 
uOoT}eODOTTe ey UeY BOoUEepscderd IejeeTH Io [Tenbe Jo Teuueyo e [eas 
jZouued ALYOOTIV GNOdW ‘“STeUuUeYO soUSpsdeId AseMOT eyy STeaeqs 7eUuW 

uOT}eUTqUOD ToUUeYO ay} sesn fT ‘/SToeuUeYO poezeodOTTe [eas Ysnu 4T JI 


"STouueryo 

poxeooTTe Teas OF ALWOOTTW GWOodwW eATnber jou seop yey} uoT eUTqUICD 
QUO PUTS 0} ‘/TapIO pot}toeds oyuy UT ‘aUITZ e& Ze sUO ‘UOT eUTqUD 
yore syooyo ALWOOTTIV GWOdW ‘esTmzeyjo ‘spssoons UuoT}eDOTTe 

ou ‘(uybuey eot) yQbueT oraz st Aeazze uoT}euTquOD TeuURYO ayy JI 


‘STeuueyo JO suOCTReUTqUOD 3sYy} JO 3suUO 

a }LOOT[e OF SETI} pue (Tid UT) eoUepedead uOT}eOOCTTe Ue pue (eed OT) 
suotjzeuTquoo [Teuueyo eTqtssod jo Aezze ue sexe} ALWOOTTIW CWOdv 
‘STauueYyo OTpNne aTdTR#[NU SsoezeooTTe jeu} pueUMIOD e ST ALWOOTTW CGNOdV 


NOIDLONNA 


S[Teuueyo oOTpne Jo joes e azeoOTTe —— ALWOOTIW GNOdW 


ALWOOTTY GWOdW/OLUTbeg/s0 TAep ‘oTpne 


pueuuoo sty} TOF ysenbey O/I ay} OF AeQUTOd ~— jsenbeyot 
SLNdNI 


‘popreiyy eTbuTs wey} ayeuwl oF penenb oie 
spueuloo TayjZO [Te pue ‘/ATOseITp peTTeo sAemTe ore spueUMIOD oeTpoUR] 
‘spueullod SOTAep [Te buTyo }edstp Fo AjtTtqtsuodsez ayy sey olutTbeg 


NOLLONNA 
TW 
‘ (ysenbeyoT ) orutbeg 
SISdONAS 


pueullod soTAep e yo 3edstp — oOlUTbeg 
AWN 


OluTbeg/eoTaap ‘otpne 


Teuueyo roy Ady yoReul WOU Ssop 
(AeyooTTW Pot) Aey uoTeD.OTTe -— NOILWOOTIVON UYYsOIAW 


AoIIS ou — 0 
:Tequmnu AOS —- JOIIG OT 

(€ nzy3 QO STeUuUeYo Of puodserIOD 
€ ny O S3Iq) peustuTy A[[N}Jssaoons sTeuueyo jJo deul yITq - 3Tun OT 


SiNdLNO 


pueuuoo ALYOOTTW GWOodW IO uoTjOUNJ soTAaequedo (Aq jes 
YOOTC O/I wory petdoo 10) Aq yes aq ysnu /Aay uot }eoOTTe —ASeYyooT[W POT 


aToAo 
querIno Jo pus ayy 3e yYsTUTy (LS) 
ATO eTpouMT YSTUTT (YWATO) -HIOAOONAS AOIAW 
ysenber O/T Atder (awa) - MOINS AOI 
>posn jou JT pereaTo oq ysnu ‘/sbheTJ — sbeTa OT 
HSINId GWNOdW ZOJ Tequmu pueuioo — puUeUMIoD OT 
(€ nzy} QO STeuUeYd OF 


puodsezi0. ¢ NIYyA CO $3Tq) YSTUTJ OF STeUUeYo Jo dew AIq — 3tTun OT 
uotjZOUNJ aotaaquedo (Aq Ayes YOoTW O/I 
WOT} petdods 10) Aq joes oq Ysnu ’/AapoU sdTASep OF AaqQuUTOd — aoTAed OT 


IeatTo st (MOINO AOI) bet} yotnb oyR jt 
ysenber O/I SeAteoer yey YWIOd abessoul 0} Taq4utod —zI0gATdey WI 


SLNAdNI 


*“TaybTy IO G [eaAeT 3dnTe\UT We Spoo 

qydnizezutT UT HSINI4 GWodv esn jou oq “AeeTO ST (YOINO AOI) HeTy yotnb 

ayy Jt (yIogATdey uu) ATuo sat{tdez pue snouozyoudASs st HSINIA CWOdW 

‘(NOILLWOOTIVON YYROIGW) Tora ue suinjezr HSINIA GNOdW yOezTTOoUT st Aoy 

UOCT}ROOTTS Ou JI ‘*(AIOAOONAS AOIGW) HeTy ouAs ayy uo Hhutpuedap aToho 

quezImMd au} Jo pua ay} je IO ATaReTpouMIT 39RTIM JUeTAND sy spIOGe 

HSINI4A GWodw ‘sserboid ut(GLIYuM GND) O9TIM e ST arTeYyR pue }OeTIOD 

st (AdyooTTw eot) Asy uoTRZeO.OTTe ey JT ‘(4TUN OT) TeuUeYo pezOeTES 

yore IOJ ‘“‘SsTeuueYo OTpne asTdIz [Nu TOT pueumoo e ST HSINIA GWOdW 
NOIDLONNA 


STeuueYyo OTpne 03 sserbord ut saq4tim yroqe —-— HSINI4 AWOodw 
GWYN 


HSINI4 GWodw/Olutbeg/a0Ttaep ‘otpne 


PETTRJ UCTCOOTTS — GHTIWAOOTIV YYHOIAW 


IoIiIe OU -— 0 

:Toequnu TOAD — TOAAIG OT 

(3x0eq eaoge aves) snouoxzyoudse JT peree[o hej YOINO AOI — sbeTq OT 
(¢€ nzry3 QO SsTeuUueYyo OF puodseTIOO ¢ 

niui 0 S}#Tq) sTeuueyo pezeooTTe AT[NJsseoons jo dew 4Iq — 3Tun OT 


SLNdLNO 


(speeoons sAemTe 0 ‘9T nary Q) 
Kerze uotjido uotzeuTquoo Teuueyo ey} jo yybueT — yYyRbueT eot 
(€ nIyuy Oo STeuUeYyo OF pucdseTIOS ¢ NYA OC 
sqtq ‘Aerze a34q) suotjydo uot }eUuTquiod TeuueYyo OF Jajyutod — eyed eOT 
pueuod ALYOOTTW GNOdwW snotaeid IO uoT}OUNJ adTaequedo 
(Aq eS YOOTQ O/I worz petdoo 10) Aq yes oq Ysnu AT 
Jastmieyqjo {key mou ajereueb 03 OFez ‘Ady UOT ReOOTTR —AdYyoOTIW eot 
(daTIVIOOTTW YugOIaw) 
Joiza umnjer ‘/STTeJ uoTReoOTTe JT (Las) 
speseo0ons 
ST TIT9 37eM /STTeJ uOTReOOTTe FT (YWATO) —LIVMON JOIdW 
(3x03 aaoqe ves) snouoryouAse 
jt ATuo ysenber O/T ATdez ATuo (Las) 
ysenber O/I ATdex (uwaIoO) - wWOINO AOI 
:pesn jOU JT pereaeTo eq ysnu ‘sbheTjy — sbeTq OT 
ALVOOTIV UNOdWY IOJ Tequmu puewuco — pueUMOD OT 
uotqzounJ sotaaquedo (Aq Yes YooTd O/I 
wolj petdoo 10) Aq jes aq ysnu ‘apou sdTAEep OF AejUTOd - BOTASq OT 
yes st (WOINO dolaw) 
6ely yotnb 10 snouorzyoudse st saqjetTdwoos uoTt}eooTTe ayy 
iajje ysonber C/I seateoear ey} WOd aebessoul 03 AoejuTod ~yNogh{dey uu 
(LZT nary? 8ZI—-) eouapeocerd uoTZedOTTe — tid UT 


SLAdNI 


‘wouj butsn peystuty ere noA useym sTouueyo poezeooTTe [Te (qq¥uq dGWodv) 
aeIjJ ysnu nok ‘/ueTo}Ss ere sTeuueyo sseTun ‘SsaouejsuMoOITO T[e Tepun 


"ueTO IS 
Huteq wory sTouueyo ay} yUueretd OF (DaUdXYW OOTTWaW) umuUTxXeul OF 


TauueUo PoeYOOT 
Teaqs oj HbuTq@duejjze uoT}eOCTTe -NATOLSTENNWHO YusOrldy 
Teuueyo roy Aasy yORew WOU Sasop 
(Aayoo[Tw eot) Asx uoT}eoOTTe — NOILWOOTIVON YaaOIdw 


IoIIS ou — 0 
:Iequmu TOTS —- IOIIG OT 
(IOITS NOLLWOOTIVON YYsOIAaW Cu) 
qoezzi00 st Aey uoT}eEoCTTR eyy JT peTeeToO He{J WOINO dOI - sbheTq OT 
(qqudq GWodv) poery you (¢ nazyy OQ SsTeuUeYo Of puodseII0O 
€ niu} 0 Ss31q) sTeuueyo payooT A[T[n}Jsseoons Jo dew 3Tq - 3tuyQ OT 


SLAdLNO 


pueuliood qLWOOTIW GWOdY 1O uoTJOUNFJ soTAequedo (Aq jes 
YOOTA O/I worj petdoo 10) Aq jes eq ysnu /Aay uoTReOOTTe —AeYOOTTW POT 


poereetTo oq ysnu ‘sbeTy - sbeTq OT Teuueyo Toy Aay YyoReuU JOU SsOop 
YOOT GHDaY IOjJ Iequmu pueuuiod — puPUMIOD OT (AaeyooTtwy Bot) Aey uoTzeEooCTTe — NOILWOOTTIVON YYsOIdY 
(€ nay} 0 sTeuueyo TOLLS OU — 0 
0} puodsazioo ¢ niy4 0 $4Iq) YOOT O03 STeuUPYyo Jo dew 4Tq - 3Tun OT -Tequmu TOIte — Torq OT 
uotTqoOuNy aoTaequedo (Aq jes YOoTq O/I (¢ nzyuz Q STeuUeYyd Of pUucdsarIOD 
wolf petdos 10) Aq jes oq Asnu ’Sepou sdOTASeP OF Jayutod — aoTAeqd OT € niu 0 S3Iq) peerjy A[[N}Jssaeoons sTeuueyo Jo dew yIq - 3tTun OT 
Testo st (YOINO AOI) HeTJ yotnb oy} FT SLAdGLNO 
qysonbet O/I SeATeoez jey yAOd ehesseul 03 AeqUTod -z10gh{dey UU 
SLOdNI pueumioos ALWOOTIW GWodwW 1O uot jounyZ soTaequado (Aq jes 
YOOTG O/I worly petdoo 10) Aq jes aq jsnu ‘Ady UuOT}eDOTTe ~ABsYyooTTW eOT 
‘apoo ydnizeqUut UT YOOT dWodw esn you Od ysonber O/1I ATdexr (uwaTD) - WOINO AOI 
"TeaTO ST (YOINO JOI) Sbety yotnb oyy jr AlTuo sat{[der pue snouozyouAs :pesn jou JT pereseToO oq Asnu ‘sbheTj ~ ShelTq OT 
ST 31 ‘ostmzeyjo /(yOINO JOI) Bets yotnb ey szreeToO 4T eseod YOTYM qaud GNOdW 1TOJ TJequmu pueuwoo — pueullloD OT 
ut ‘/q0azTI00 st AY UOTRROOTTR ey} JT ATUO snouozyoUASe ST YOOT AWOdW (€ nzy} OC STeuUReYo 
0} puodserzi0os ¢ NIYy CO $}#Iq) seTjJ 02 STeUUeYO Jo deul yTq - ytTuQ OT 
‘uoTJeTdWOD sUOT}eDOTTe TeyjOuR uO jUepuedep sTeuUeYyoO USaTO S uotTzouny sotAsquedo (Aq Jos YOoT O/I 
Jo butaery oy} aeyeul Jaaou ‘yooTpeep etTqtssod e pToae Oo], ‘“eTqrssod se wory petdos 10) Aq yes aq ysnul ‘apou aodTAap 0} JaqUTOd — adTAad OT 
ucOS Se PeseTjJ oq PTNOYS sTouUeYO aUuy ‘/TOTTe sty} yATM (yogATdey uu) I@aTO ST (MOINO AOI) betT}y Yyotnb ayy jt 
pettder st yoo, ayy JI *(NSIOLSTISNNWHO YNAOIdW) Torre ue jsonber O/I saaTacer ey} 310d aebessoul oF JaQjuTod -ZrIogATdey uw 
suinjei pue set{Tdet yOoT dWodw ‘/sanooo [ees e JI “sTeuueYyo pexooT 744 SLAdNI 
aUO TReyS 0} SyduB}We UOCT}ROOTTe soUepsdcead AeybTy e sseTuUN ‘pest o1e 
SYOOT YI sToauueyo ey} TTe Trqun (qrogATdey uu) ysenbez C/I eyy ATdez ‘apoo ydnizeqUuT UT agua GWOodW esn jou og ‘TeaTO ST (MOINO AOI) bers 
jou ssop yOOT GNodWw °(4TUA OT) S}Iq JOeTeS TeuUeYyoO ay} STeEeTO YOTYM yotnb ayy Jt (qIogATdey uu) ATuO set{dez pue snouozyouds st gayd CNOdW 
‘(qqgud GWodv) wey butesezy Aq ATuo peyooTun eq ued sTeuUeYyo pexooT -(NOLIWDOTIWON YNSOIGW) rOTTe ue surnjzeT Aqyud AWOdW ‘oesTMTYyIO 
“peyootTun ere sTeuueyd ey} [T}UN Tem “ToeuueyoO sy AOJ 
0} ‘suoT}eOOCTTe (LIYVMON JOIdW) 3TemM—-ou uaAe ‘SsuOT}eDOTTe souepecdeid Hbutqtem (ALWOOTTIW GWOdwW) sqysenber uoT}eooTTe erie sTey} JT syooyo 
IeybtTy [Te sesneds YOOT aWOaW ‘/TTeJ OF sUOT}eODOTTe quenbsesqns pue ‘3zsenbez O/I YoOT ey3 
[Te esneo prTnom yotum (ogNaXWW OOTT¥aW) umuTxeul 0} (a0TAequedo sot[der aqua GWOdW 3eS s}Tq TeuUPYyo ou sey YsenbeT O/I YoT ayy FI 
IO YLWOOTIV GWDGW /OeuYdLaS GWoaw) eouepecerd ay} butqjes exTTUN ‘qsonber O/I YOoT ey} UT (4TUQ OT) TeuURYyo sy OJ Iq sy Sesto 
pue 4T syooTun gqgud GWodW (MOOT GWOdW) peYyoo,T st Teuueyo oy} FI 
‘sTeuueyo Aue YOOT OU "uOoT}eOOTTeeT TOJ aTqe[teae TeauuPeYyd ay} soeyeul 
TITM pue (NOILYOOTTVON WumOIdWY) Tora ue suInzetT YOOT AWodW ‘esTMIey4O pue ‘Asx uoT}eoOTTe sTeuueYyo sy} sebueyo 
‘Teuueyo ayy butTeeys worzjy (aoTaequedo 10 ALYOOTIW GWodw) suoT ecOTTe ‘CLASSY GWD) 2484S UMOUY e OF TeUUeYoO oY SeT0O Se 
Quenbesqns butjueaeid /Teuueyo oy} SYOOT WOOT GWodwW ‘3}0e1T00 :DUTMOTTOJ oy} SeOp agua GWodw ‘30eT10D 
st (Aayoot[w eot) Aey uotzecsoTTe ey Jt ‘(4TuQ OT) TeuuReYyo pejoeTes st (AayooT{Ty eot) Asx uot}ZeooTTe ayy JT ‘/(4TUN OT) TeuUeYo pejosTesS 
yore Jog ‘sToeuueyo otpne aTdt3z nu rOJ pueuwmlioo e ST WOOT GWodv yore 10g ‘sTeuueyo oTpne aeTdty[nu TOJ pueumioo e ST Agua CGWNOdW 
NOILONNA NOTLONNA 
uaTOIS buteq wor} sTeuueYyo OTpNe juaacid —— YOoT ANodwv UuOCT}eOOTTe TOJ sTeuueyo OTpne serj -- AaYd GWNOdW 
GWYN GWYN 


MOOT GWOdv/OlUTbed/eoTASp ‘oTpne qgud GNodw/olutbeg/aotaap ‘otpne 


B- 10 


Teuueyo roy Asx yo eu JOU sasop 
(Kayoottw eot) Asy uoTReooTTe — NOITLWOOTIVON YagsOIaw 


AIoI1Se ou — 0 
:Iequnu TOTS —- TOILY OT 

(¢ nzu2 0 STeuUReYo OF puodserI0OD ¢ nIYyy CO S34Tq) 
aouapadseid yes AT[NJsseoons zey} sTeuueyo jo deul yITq - 3tugQ OT 


SLNdLNO 


pUPUMIOD ALWOOTTW GWodw TO uotTjounz asoTaequedo (Aq jes 
YOOT O/I wory petdoo 10) Aq yas aq ysnu ‘Ady UoTReDOTTe —ASYoOTTW eOoT 
qysonber O/I Atder (uvg1D) — MOInNO dOI 
:pesn jou JT perzeeTo eq ysnu ‘sbeTy — sbe[Tq OT 
OdUdLES AGWOdW tO} Tequmu pueumoo pueUOD OT 
(¢ niuQ 0 SsTeuUeYyd OF puodsarI0OD 


€ NIU QO S3Iq) soUepederd Jos OF STeUUeYO Jo dew 4Tq — 4tun OT 
uoT}oUN} sotasequedo (Aq yas YooTq O/I 
wory petdoo 10) Aq yes aq ysnu ‘apou soTASep O} AajUTOd - aoTAed OT 


IeaToO Sst (YOINO JOI) bety yotnb ayy fT 
ysonbert O/I Ssaatacoer ey WIOd abhessoul 032 IayuTOd ~y1ogATdey wi 
(LZT Nay BZT—-) eoUSpedezd uOoT}eDOTTe Mou — Tid UT 


SLAdNI 


‘apoo ydnizequt ut OsudLES AWOdW esn jou Od 
‘reatTo st (worInd JOIL) HelTy yotnb ayy st ATuo (310gA[day uu) sattdez pue 
snouozryoudS ST O9udLES GWOdW ~‘(NOILWYOOTIVON YYysOIGW) 1OrIe ue sumM}er 
OFUdLAS GWOdW ‘/eSTMIeyjO ‘/TeuuRYyo ayy IOJ bHutzTeaM (ALWOOTTW CWNodw) 
Sjsenber uoT}eoOTTe aouepeceid—1rayhbty ere eTey} JT syooyo pue (iq UT) 
ONTRA MoU e OR BOUSPsdeId UOT }eDOTTe |e SOS OAUdLES AWodw ‘}0e1I100 
st (XeyooTTw eot) Aaey uoTtjeooTTe ayy Jt ‘(4TUN OT) TeuUeYyo pejoeTES 
yore IOq ‘STauueyo oTpne aTdtyzTnw ToJ pueumioo e ST OAUdLAS GWOdW 


NOIDONN 


S[euueYyo OTpne TOJ aouapacard uoT}eOOTTe ayy eS —-— OsUdLAS ANodw 


Teuueyo AOJ Ady yo eu jou ssop 
(AoyooTTW eot) A@ey UOT}PeOOTTe — NOILWOOTIVON YusOIAY 


SENAdLNO 


IoIIs ou — @) 
>Jequmu AToOIIS — IOIIG OT 

(€ nzyi QO STeuUeYo OF pucdseTIOD ¢€ NAY CQ $FTq) sumToA 
pue potied pepeot AT[InJsseoons ey  sToeuueyo jo deul ytq ~— 3tuQ OT 
(zeauTT ‘~9 NIYA Q) SUMTOA MoU — OSUMTOA eOT 


(uLIoJaAeM UO HhutTpusedep 

00S 03 00€ MOTeq SY¥IOM Tsez[T} HbutsetTe-Tjue ‘9EGCc9 
niyi /ZT) SqueueroOUT su G9f°6/Z UT potted oTdures meu — poTied eoT 

pueuloo ALWOOTTIWY GWOdW 1O uoTjZouNny eotaequedo (Aq jes 
YOOTA O/I worj petdoo 10) Aq yes oq ysnu ‘Ady UOT}eDOTTe —~KdYyoOTTY eot 

aToXo 
quarimmos jo pus 3uy .e YystuTy (Lys) 

ATayetpout ystuTy (YWaTO) -HTOADONAS dJOIdY 

ysonber O/T ATdexr (aWaTO) - WOINO AOI 
:pesn OU JT pereaeTo aq ysnu ’sbeT} — sbe[Tq OT 
TOAUAd GNOdW Io} Jaqumu pueuwco — pueumlod OT 

(¢ niu 0 STeuUeYo OF pUOodsazITOD ¢€ NIYA 


0 S31Tq) eumToa pue potied peoT oF sTeuueYyd jo deul 4Tq — 3tun OT 
uoT}oOUNJ eotTAequedo (Aq Joes YoTq O/I 
woiy petdoo 10) Aq yes oq yYsnu /apou soTAap OF AaqUTOd - ao0Taseqd OT 


IeatToO St (MOINO JOI) Hertz yotnb ayy jt 
qysonber O/I saatTecer ey} WIod aehessou 03 TequTod —710gATdey UU 


SLAdNI 


‘“ZaybtTy AO Gg TeaeT ydnizTeqZUT 7e spoo 

qdnizejUT UT TOANSd GWOdW esn you oq ‘“TeeTO ST (MOINO JOI) beTF yotnb 
ay} yt ATuo (j10gh{Tdey uw) setTdez pue snouozryouAS ST TIOAUdd CGWOdW 
‘(NOLLWOOTIVON YYaOIdW) ToIze ue surnqez ToAudd aWodw /}OerTOOUT st Adyx 
UuOTFeOOTTe Ouy JI “(ATIOADONAS dOIadW) betTy ouAs ayy uo butpuedap ‘atodAo 
quariinos ay} Jo pua ou} ye IO Aja jetpoumIT potied pue oumTOA MoU e SpeOoT 
TOAUSd GNOdW ‘’sserboid ut (ALIYM GWO) Oo3TIM e ST eTeyA pue 3o9TTOD 

st (Xayoot[Tw eot) AeY uoTPeEoOTTe ayW JT ’(4TUA OT) TeuURYO pe JoETES 
yorea Jog ‘sTeuueyo OTpne aTdt4[nu A0J pueuwoo e ST TOAUTd ANOdW 


NOILONNA 


STeuueyo otpne 
0} sserboid ut Sa}TIM IOJ sumT{oA pue potrzed oyy ebueyo -— TOAuad AWOodv 


11 


AWWN GWYN 


qd LAS GNOdW/OLUTbeg/eoTAap ‘otTpne TOAUdd GNOdW/OlLUTbeg/eoTaep “otpne 


Teuueyo AoJ Asay yo eu’ WOU ssop 
(AayooTTW eot) Aey uoTZeOOTTe — NOILWOOTTIVON YysOIaY 


ueToO Ss 
Teuueyo 10 (O1WTOGY) peTeouRD - GaLYOdY YYaOI 
ToiII9a ou - 0 
:Iequnu TOIIS — IOIIG OT 
Teuueyo psyoeTes 
au} UO ssaerboid UT ST 3}TIM & JT pereato beTj YOINO AOL —- sbeTq OT 
(¢ nu} 9 STeUuUeYyo OF puodserIOS ¢€ NIYy} CO $4Tq) 
atoko AOJ peytem AT[NJssaoons yey} Teuueyo Jo deul yTq - 3tuq OT 
SLAdLNO 


puewwoo ALVOOTIV GWodw 10 uot joOUN; aotaaequedo (Aq jes 
YOOTA O/I wWorjy patdoo 10) Aq yes aq ysnu ‘Ady UOT }ROOTTL _Kayoo[lw eot 
payetTduios sey aToAo e pue 
Tauueyo pejoetTes ey} uo sserboird ut 
ST 03T1M e Jt ATuo ysoenber O/I Atdex (Las) 
ysonbaz 0/1 ATder (uwaIo) — WOInd AOI 


:pesn jou JT pereeTo eq 4snu ‘sbheTjy - sbeTq OT 
Teuueyo 103 AVY yoReur WOU SZOpP FTOROLIWM GND 10} Jequmu pueuico — puPUOD OT 
(AayooTTw eot) Aey uotzeooTTe — NOILVOOTIVON YaaOIay ‘pesn sT [auureyo Tequmu 4Tq 4SeMOT ‘eS ST 
4toiie ou —- 0 Iq auo ueyy aeTou JI “(¢E nIYyW O STEeUUeYO 03 pucdseTIOS 
:Tequnu TOITS — ZOIIG OT € NIM Q $31q) aToAD TOF Tem OF TeuUeYO Jo deul yTq - 3TuQ OT 
(¢ ny 0 STeuUueYyo 0} puodserIOD uoT}OUNJ aotaequedo (Aq yes YooTq O/I 
€ niu} 0 $31q) pezeatTo AT[NjJsseoons sTeuueyo Jo deul #1q - 3tuQ OT worjy petdoo 10) Aq jas aq ysnu ‘/apou aodTASep 0} Tejutod - BoTASd OT 
SLNAdLNO pe yeTdwoo 
sey aToko e pue Teuueyo payzoeTes ey} uO sseiboid 
pueUMOD ALWOOTIW GWodW Io uoTjzounjy eotaequedo (Aq jes UT ST O}TIM & JT TO /2TeaTO ST (YOINO AOI) HetTy yotnb yy 
YOOT O/I wory petdoo zo) Aq yes eq ysnu /Aay uoTRzeDOTTe —-AeyoOTTW Pot JI ‘/ysenber O/I seatTeoer }eyR Mod ebessoul 03 TazuTod —WIogdTdey UUW 
ysenber 0/1 ATder (awa91D) - MOINO dol SLAGNI 
:pesn jou JT pereeTo eq ysnu ‘/sheyTF - sbeTyq OT 
YWITIO GWO OJ Tequmu pueuioo — pueumlloD OT ‘Zaybty IO G TeaeT ydnizezUT 7e Bpoo qdnize ut 
(€ nzy} QO STeuUuRYyo OF UT FIOADLIVM GWOdW esn jou og ‘“AeSTO ST (WOIND AOI) Hetty yotnb 
puodsaiioo ¢ nIy} 0 S$}Tq) TveToO 03 sTeuueYyo Jo dew 4Tq - 3Tun OT ayy Jt ATuo settdez pue snouoryouds st 3T ‘astmreyzO /(MOINO AOI) betsy 
uoT}oOUNJ eotaequedo (Aq yes YooTq O/I yotnb au} sTeaToO RI aseo YyOTUM UT /aqeTduoo 03 aToOAD e IOjZ buTzTeMm 
wozrj petdoo 10) Aq yes eq ySnuU /apou adTAEp 03 JoqUTOd - adTaeEd OT ST 41 yt ATuo snouoryoudse st AIOAOLIWM GWOdW ~«(aLWOOTTW aWodw) 
TeajTo ST (WYOINO HOI) beTy yotnb ayy FT UaTOIS ST TeuueYyo ay} Io (OIWoqy) peTecuro ST }T Jt (GaLYOGW YUYSOT) 
qayje ysonber O/I seatTeoer yey} Pod ebessou 07 Zayutod —310gATdey uu AoIIS ue SsUIN_eT FIOADLIVM GWOdW ~*~ (NOILWOOTIVON UYugsOrdy) 
SLAdNI qoiia ue suInyeT FIDADLIWM GWodW /}OeATOOUT ST ABy UOT}eDOTTe 
au} JI ‘“ATezetpouwt set{[der AIOAOLIWM GWOdW ‘ssaiboid st o3TIM OU 
‘TeaTO Sst (yOINO AOI) Hety yotnb oyz xt ATuo (jrogATdey uw) ST aTau} JI ‘eTokO Quazimmo ayy jo pue oyy [TUN (yogATdey uu) ATdaz 
Sot{dei pue snouoryouds st yWSTO CWO ~(NOILWOOTTWON uuaOIdy) jou seop FIOADLIWM GWody ‘Teuueyo peyoetTes uo sserborid ut (ALIYM CWO) 
Joiia ue summer yWwHTD GWO ‘estTmTeyjo ‘buTYyOU SeOp YWATD AWO ‘3o0eTIOD OUTIM & ST aTOYyQ pue yoeTIOD st (AByOOTTW eOT) Asay uot}eooTTe ey ji 
st (AeyooTtw eot) Aey uoTPeoOTTe sayy JT ‘(qTuQ OT) TeuUueYd pejzoeTes *(4TuQ OT) TeuueYyo OTpne oTbuts e TOF pueumloo e ST FIOAOLIWM GWOdW 
yoea Tog ‘sTeuueyo oTpne oTdty[Nu TOF pueumlod pxzepuejs e ST YWATO AWO NOLLONNA 
NOILONNA 
a}TIM e Jo aToho 
ssyoeo [euro Ut Aeme mozry} -~- uvaIO GNO qUuazTImMd) ayy syeTduiocd OF TeuueYyo OTpne ue TOF FTeM —— AIOADLIWM ANOdW 
GWYN GWYN 


YWATO GNO/OLUTbeg/aoTaap oTpne APTOADLIVM GWOodW/OlLUTbeg/a0TaAap ‘oTpne 


B- 12 


ssoiboid 
ST QUOU FT OLazZ /a}TIM JUSTIN TOF YOoTA O/I OF Tequtod - eed eoTt 
Teuueyo rz0y Ady YoReu YOU SsOp 
(AayooT{w eot) Aey uoTZeooTTe — NOILWOOTIWVON YYsOIAY 


[euueyo Toy Ady Yo Jeu JOU SZOp 
(XayooTTwW eot) Aaeyx uoT}PeEoOTTe — NOILVYOOTTVON aesOIdy 


IoIIa ou — 0 IoZIIs ou — 0 
:Taequmu AOS — IOIIG OT :Joqumnu TOS — IOAIG OT 
(¢€ ny} O TeuueYyo Of SpuodseTZ0D (¢ nzy2 Q STeuURYo O03 puodserZOD 
¢ niy3 0 31q) peer AT[NjJssaoons Teuueyo jo dew yIq — 3tTuQ OT € naiu4 0 $3tq) peysnty AT[nN}Jsseoons sTeuueyo Fo dew 41q — ytun OT 


SLAdLNO 


pueuwoo ALWOOTIW GWodwW 1O uoT oun; aotasequedo (Aq jes 
YOOTA O/I wory patdoos 10) Aq yes oq ysnu ‘Ady uoT}PeooTTe —-AeyooTTW eot 
ysonbez 0/1 ATdexr (yweIO) -— WOInNd AOI 
:posn jou JT pereeTo aq ysnu ‘/sbeTy -— sbe[Td OT 
away GWD 1TOJ Tequmu pueUMWOCd pueuwloDd OT 
"peat [Teuueyo AJequmu 3Tq 


SLNAdLNO 


pueuiod ALWOOTTIW GWodw 1O uotjouny aotaequedo (Aq jes 7 
YOOTA O/I wory petdoo ro) Aq yes eq 4snu ‘Kay uotzeosoTTe —AeyooTTW eot 
qasenber 0/1 ATdez (awaId) -— WOINO AOI 
:pesn jou JT pereeTo eq ysnu ‘sheT} — SbeTA OT 
HSnTa GWO ZOJ Xequmu pueumlod - pueuwoD OT 
(e€ nzy3 Oo sTeuueYyo OF 


ysamoT ‘eS ST 3Tq aUuO UeYZ eTOW JI “(E NIU OQ TeuURYOo puodsaiio0os ¢ niuy Oo S3tq) ysntTF OF SsTeuUueYo Fo deul Tq — 4tug OT 
0} spuodsaz10. ¢ NnIy C0 3Tq) peer O32 TeuUeYyo Jo deul 4Tq — }tuQ OT uoT}yoOuUNJ sotaequedo (Aq yes YOoTW O/I 

uoT}OUNJ eoTasquedog (Aq yes YOoTA O/I1 woljy petdoo 10) Aq jes eq YsnU ‘epou BdOTASP OF qeqyutod — dad Tae OT 
worj patdoo ro) Aq yes aq 4Ysnu /apou adTAep O} AayjUTOd - SOTASd OT reato st (yOINO AOI) Hbety yotnb ey} FT 


Aeeto Sst (MOINO JOI) HelJ yotnb sey A jt 


Tajje ysenber O/I seateoar jey  yzod abessau oF Jayutod ~yrogATdey uw 
S.LAdNI 


‘IeaTO st (YOINO AOI) 31Tq Yyotnb osyW Jt ATuo 

(qx0gA[dey uu) satTTdez pue snouozyoudS st qway GWO ‘O1ez suInjer 
quay dWo ‘ssezbord ut 23T1mM ou ST eTey} JI *(NOILWOOTTIVON uuaoIdw) 
rIoizae ue suinjer quay GWO ’astTazeyjzo /TauueYd pazoeTes 9uz 

uo (GLIUM GND) 6butytim ATjueTIMS yooTq O/I ey} 03 (e zed OT) AajUTOd 
e suinjel quay GWO /}o0erTTOD st (AeyooT TW eot) Aeyx uoT}eooTTe eyW JI 
-(4TIug OT) TeuUeYo OTpne aTbhuTs e ITO} pueuwioo prepuejs e ST away dawo 
NOLL 


qutod Atjue O/I Teumou —- qvay dWo 


INN 


jsanber O/I SaeaTeoez 7ey  WIOd abessoeul oF Zequtod —y10gATdey uu 


SLAdNI 


‘qaybty Io ¢g TeaeT ydnazrejzUT 3e Spoo qdnazajut ut HSNTd GWO esn 

30u og =‘AeeTO ST (MOINO AOL) Sets yotnb ayy yt ATuo (yroddTdew uu) 
sottder pue snouozyouds st HSATA GWO ~*(NOILWOOTTIVON Yuaoldy) 

zoriie ue summjer HSNTd GWO /estmrmeujO / (ATIOAOLIWM GWodw) 

aToko ay} Jo pue 3y} UTM eztuoryoUAS 0} HutytTem sysenber O/I Aue pue 
ponenb 10 sseiboid ut (aLIYM GWO) sejTim [Te szToge HSON14a AGWO ‘3}0eI1L09 
st (AsyoottTy eot) Asx uoTZRoOOTTe Sy; FT ‘(4Tun OT) TeuuReYyo pezoeTes 
yorsa oq ‘“sTeuueyo OTpne aTdTyTNu TOF pueumloo prepuezs e ST HSN'ld CAWO 


NOILONNA 


O/I butpued TTe Teoueo —~ HSNTA AWNO 


13 


GWAWN AWN 


dvau dWo/olutbeg/aoTaep ‘otTpne HSNTa GWO/OlUTbeg/aoTaep oTpm 


Teuueyo Toy ASY yo eu’ JOU SVOp _ 
(KayooTTw eot) Asx uoTtyeooTTe — NOILWOOTTVON wudoOldy 


Teuueyo i0oj Asx YoeU JOU ssop Ioiia ou — 0 
(KayooTtw eot) Asx UCT}eOOTTe — NOILWOOTIVON YusOlaw -Tequnu ACIS — IOILF OT 
IoII9e ou — 0 (¢ nau 0 STeuUReYyo 0} puodserI0D 
:Zequmu TOTS — IoIIq OT € niu 0 $3Tq) yeser AT[N}Jsseoons OF sTeuueYyo JO dew 4Tq — 4tun OT 
(¢ nzy3 QO STeuUeYo O03 pucdseTI0OD SLNdLNO 
€ niu 0 S31tq) peyrejs AT[NJssadons sTeuueyo jo deul yTq - qtun OT 
SL~NAdLNO puewos FLYOOTTW GWodw 1o uoT}ounj eoTaequedo (Aq jes 


YOOTd O/I wory petdoo zo) Aq yes oq ysnu /Aay uoTZeOOTTe —ASYOOTIW POT 
ysonber 0/1 Atdexr (awaTO) - WOINO AOI 

:pesn jou JT pereatTo eq ysnui ‘/sbeTy — sbeTd OT 

LASaY GND Io} Tequmu pueuIOD — PpUPUMIOD OT 
(¢ nzyy QO SsTeuUReYyo OF 


pueulloo ALWOOTTIW GWOdW 1O uotjounj aotasquedo (Aq jes 
YOOTG O/I wory petdoo 10) Aq yes oq ysnu /AdyY UOT}eOOCTTe —KayooT[W Pot 
qsoenber O/1I ATdert (uwaIo) -— MOINO dol 


:pesn OU JT perzeaTo oq Asnu /sbeTy — sbe[Td OT 
LYWLS GWO ZOJ ZTequmu pueumioo — pueUMoD OT puodsez109 ¢ NI} 0 S}1q) JeseT 0} STeuURYO FO deul 3Tq - ytun OT 
(¢ ny} Q sTeuueYo OF uoTjOUNJ sotaequedo (Aq yes YOoOTA O/I 
puodseri09 ¢ nay Oo S3tq) Wes OF STeUUPYO JO dew 31q — 3tun OT woij petdoo 10) Aq yes eq ysnu ‘Qpou SoTAZpP OF Ta yutod — aoTAsd OT 
uoT}oOUNJ sotasquedo (Aq Jes YooTq O/I zeato st (WOIND JOI) bety yotnb eyy JT 
woij petdoo 10) Aq yes eq Ysnul ‘apou soTAep OF TeqjUTOd — sdTAad OT qsenber O/I SeATeoer eu 4Od ebessoul OF Tayzutod -z10gATdey uu 
SLNAdNI 


Ie2TO ST (WOINO AOI) HbeTJ yotnb ayy Jt 
Tayje ysonber O/I saateoer Zey} Wod ebessou 0} Za zutod —z10gATdey uu 


SLNdNI ‘Zoyubty IO G TeaeT 4dn1rTE8AUT 


ye apoo 4ydnize4UT UT LaSaY GWO esn jou oq “AeeTO ST (MOINO AOI) berly 
yotnb ayy jt ATuoO (q20gh{Tdey uu) sat{tdez pue snouoryoudSs st LASaY CWO 


‘Toybty IO G TeaeT 4dnizzrejUT 7e sapoo qdnizejut UT LYWLS GWO esn jou og 
-(NOLLWDOTIWON UNFOIGW) ToIZe ue suinjet LESAN AWO ‘esTMreYyyO 


-reaToO ST (YOINO AOL) HetTy yotnb ouyz yt ATuo (rodATdey uu) sottderz 

pue snouozyouds st LYWLS CWO “pexTw ere sqyndjno atey pue uwrojasem oures 
au} butAetd ore sTeuueyo 9yy JT UOTPIORSTp ozTUTUTU OF A[snooue} [nurs 
sTouueyo eTdtTzTNu sq7ejs LYWLS CWO ~*(NOILWOOTTIWON uugordy) 

zoize ue summjel LYWLS GND /}oeTTOOUT st Aayx UOT eDOTTe 

aya JI ‘“Teuueyo oy} 09 (ALIUM GWO) SeqzTIm [Te spies ATO ReTpoUMIT 

LYWLS dWo ‘’(dOLS GWO) peddoys ATsnotaeid sem TeuueYyo sy} pue joaeTIOD 

st (XeyooT{Tw eot) AsY uoT}JeooTTe ayy JT ‘(4TUN OT) TeuUeYoO pszoeETesS 


‘(dOLS GND) peddoys st 4t JT Teuueyo sy sdojsun 

pue ‘(HSQNT4a GNO) O/1 Bbutpued [Te sTeouro 

‘ZJoVOeA YdNni3ezZUT OTpNe su Ses 

‘s}Tq yor}ze pue siJaystTber oTpne ereMprey oy} SiesTo 
*LHSaY GWO ’3OeTTOD 
st (AayooT{Ty eot) Aex uoT}PeEooTTe Syy FT ‘(43TuQ OT) TeuUReYo poe zosTesS 
‘sTeuueyo oTpne aTdty[Nnu TOF pueumloo prepueyjs ke ST Lasay GWO 


yore Tog ‘“sToeuueyo OTpne aeTdTz[Tnu TOF pueuwloo prepurjS e ST LUWLS AWoO yore 107 
NOILONNA NOIDLONNA 
(O_ eXxTT) Hutsseooid aotaap yes --— LYWLS CWO a3e4S UuMOUY & OF DOTASP 3TO}SSLT —— LaSaYy dWo 
GWYN 


GWYN 


LYWLS GNO/OLUTbed/e0TAap ‘oTpne LaSSY GWO/oluUTbeg/a0TAap * otTpne 


14 


Teuueyo Toy ASY YoReul ZOU SsOp o 
(Aayoottw eot) Aey uoTReEOOTTe —- NOILWOOTTIVON YusOIAY 


Ioiie ou — 0 
:ZJaqunu TOTS — IOILG OT 
Teuueyo Toy Asy yo eu Jou ssop (¢ ny} Q sTeuUuPYyo O03 puodseir10D 
(AaYOOTTY eot) Aaey uoT}edOTTe — NOLLWOOTIVON YNSOIGW ¢ niu3 0 $31tq) peddoys AT[NjJssaoons sToeuueyo Fo dew 41q — 3TuQ OT 
ioiie ou — 0 SLAdLNO 
:Iaqunu TOTS -— IoIAW OT 
(¢ nzIyi QO STeUuUeYyo Of pucdssr1OD pueumioo FLWOOTIW GWodwW 10 uoT JOUNy aotasequedo (Aq jas 
€¢ niu} QO $3Tq) peyepdn ATT[NjJssaeoons sToeuueyo Jo deul 4Tq — 3tTuQ OT YOOTG O/I wor1y petdoo 10) Aq jes aq }snu ‘Kay uotzeoo,Te —AeyooT[TW eot 
SLAdLNO qysonber 0/1 ATder (avgaTD) - WOInd AOI 
:pesn OU JT pereaTo aq ysnui ‘sbeTjZ - SbheTq OT 
pueumiod ALWOOTIWY GWodv IO uotjzounJ sotaequedo (Aq yes dOLS GWO ZIOJ ZJequmu pueuMiod — pueuMloD OT 
YOOTC O/I wory petdoo zo) Aq yes aq ysnu ‘/Aay uoTReEDOTTe —ABeyooT[W eOT (€ niu} QO sTeuueYyo 
ysonbet O/I Atdexr (uWwaID) -— WOINO AOI 03 puodserz0o ¢ niu} O S}#Tq) doys 03 sTouueyo Jo deul Tq - 3tun OT 
:pesn jou JI pereeto aq ysnu ‘/sheTy — s6eTd OT uotzoUNZ aeotaaquedg (Aq yes YooTW O/I 


worly petdoo 210) Aq yes aq Ysnu ‘epou sodTASpP OF Jajutod - BoTAsd OT 
rreayTo Sst (MOINS JOI) Hety yotnb eyy jt _ 
Taqje ysenbez O/I seATeoer 3eYA 310d abessou 0} Tajutod —jz10gATdey uw 


ALWddN GWO 1IOJ Tequmu pueuwlioo — pueuMlod OT 
(€ ny QO STeUUeYD OF 
puodsezi0os ¢ ny QO S3Tq) azepdn oF SToeUUPYo Jo deul 4Iq - 3tun OT 


uotTjoun}y asotaoquedo (Aq jes YOOTC O/I SLAdNI 
woly patdoos zo) Aq yes eq 4ysnu ‘apou eodTAep OF TeqUTOd — adTaad OT 
Testo st (YOINO JOI) bel} yotnb ayA jr ‘TeybtTy 
daqje ysonber O/I saaTacoer yey Wod ebessou 0} AeqUTOd —7I0gATdey Uw IO G JTeaeT AdnizezUT ze Spoo qdnizezUut UT dOLS GWO asn jou og ‘“AeSTO 
SLNANI St (YOINO AOI) SetTy yotnb ey Ft ATuo (y10Gk{dey uw) seT{dez pue 


snouoryouds ST dOLS GWO “TeuueYyo ey Sj}eSet LaSaY GWO 1O TeuuReYyo oyy 

sqreis LYWLS GND [TTjuN [TeuueYyo peddojs e 03 so3TIM dn sanenb gLIYM dWO 

‘(NOITLWOOTTIWON YUYFOIGW) TOITS ue suimMyjer dOLS GWO ‘’estmzeyj0o /sseibo1id 

UT (4LIYM GWO) Se3TIM Aue sdoqs ATe,etpeuit dOLS CWO /’30e7TOD 

st (KeyooT{Tw eot) Aex uoT}PeooTTe sayz FT ‘(qTuQ OT) TeuueYyo pajoeTes 

‘sTouueyo oTpne aTdtT}z[Nu TOF pueumoo prepuejs e ST dOLS AWO 
NOT LONNA 


“TROTO ST (YOINO JOI) HeTJ yotnb ayyz yt ATuo (zr0gATdey uu) sat{dez 

pue snouoryouds st aLYddN GWO ~(NOILWOOTIVON uugoIdw) to1ze 

ue sumnjel glvddn GND ‘estateyjo ‘/buTyjou seop ALWddN GWO ‘3OeTIOCD ST 

(AsyooTTw eot) Aey uoTReoOCTTe ay JT ’(4TUN OT) TeUuUeYyo pajoaTes yore 

Iog ‘SToeuUueYyo OTpne aTdty[nu TOF pueumoo prepueys e ST ALWddN CWO yoes 10d 
NOIDLONNA 


(S_ eXTT) butsseooid sotaep dojs —- dOLS GNO 


qno siejing ARZITp eorOJ —- ALYddnN GWO 
GWWN 


AWWN 


ALWddN AWO/OlUTbeg/eoTAep otpne dOLS CANO/OlUtTbeg/a0TAap ‘oTpne 


15 


Teuueyo roy Asay yoReu You saop 


(AayooTtw eot) Asx uoT}eoOT Te — NOILWOOTIVON UYYaOIAY 


uaeTO Ss 

Teuueyo AO (O1RAOqY) peTeoueRed — GaLYOdW YYAOL 
IoIAS ou - 0 

:Jequmu AOTAS — IOIIG OT 

IOIIS OU ST STdYR JT peres[O HelTJ WOINo AOI — sbeTq OT 
(¢€ nzryA QO TeuuReYyo OF spuodsar10.D 

€ niyo 31q) uaqATAM AT[NJssoeoons Teuueyo jo dew 4Tq —- tug OT 

SLAdLNO 


AOVSSHWALIUM AOICY 
Aq peTqeue Jt ‘’e3TIM Jo RZIeWS We peTtT[der obessou —HsWoeqyTIM eot 
(azTuTyutT 
ToT Qo ‘SESS9 NAYA QO) AeTTe ZeadeT 0} SOUT JO Aequmu — SaTOAD eOT 
NOAUAd JAOTaGY AQ peTqeue Jt /(reaUTT “79 NAY OQ) SUMTOA — osUMTOA eOT 
TOAUad AOIaW Aq paetTqeua JT /(wItoyeaem 
uo bHbutpuedep 00S OF OOE MOTE SyIOM TeR[TJ HutsetTe—-Tyue 
‘96669 NITY? LZT) SJUSUIETOUT SU G9E°6LZ UT POTied eTdures - poTiaed eoT 
(ZequMNU UeAS aq 
4snu ‘Z/OTET nay zZ) seqdq ut Aezzre saem dy JO YQHUeT — YRYbHueT eot 
(peubt{[e-p10M pue WWY eTqesseippe dtyo wo ysnd ut 
(LZT nazyuy gzt—-) seqAq poubts) AexrTe wrojyaaem Oj} Jaqutod — eyed eot 
pueuiod FLYVOOTIW GWOdW IO uot OUNJ soTasequedo (Aq Aes 
YOOTC O/I worjZ petdoo zo) Aq jes aq jsnu ‘Ady uOTJeDOTTe —AdYOOT[W eOT 
qzrejs a4TImM ye ohessou ATdaer (Las) ~ FOWSSSWALIUM AJOIGW 
potied pue oumToa peoT (Las) - TOAUdd JOIdW 
:pesn jou JT pereayTo oq ysnu ‘sheTF — sbeTq OT 
ALIYM GND TOJ Tequmu pueuwuwod — pueuMod OT 
"Ud}3TIM ST TouUeYyo Tequmu 4Tq 
4YSOMOT ‘ES ST Tq DUO UeUA eTOU JI “(€ NAY C TEeUUeYo 


03 spuodsez109 ¢ NAY CO 31q) Oe4TIM OF TEeUUeYO Jo deul ATq — 3tun OT 
uoT}OUNJ asotaaquedo (Aq Aes YOOT O/I 
wolj petdoo 10) Aq jes aq jsnu ’apou soTAap OF AaquTOd — adTAed OT 


SazeTduioo 3a4T1IM 3Uy 
Jeqzje ysenber O/I seateoer 7eyR WI0d ahessoul 097 AaQuTod —jA0gA{Tdey uN 
SLNAdNI 


‘ZaybtTy IO ¢ TeaeT 4dnzzsaqjut ye epoo ydnzzoejzutT UT ALIYM AWO 

asn jou Og ‘“TeeTO ST (YOINO JOI) Hety yotnb ayA Jt ATuo sat{tdazr pue 

snouoryouds st TI ‘/astmzeyjo /but}z4TIM soysTuTyZ AT Taqje (qa0gATdey uw) 

qsoenber O/I ey set{tdez pue (YOINO AOI) beT} yotnb ayy sirzeato 

31 eased YyOTYM UT ‘’TOITe OU ST aTEYy JT ATuO snouoryouAse st ALIYM GWO 

*(GIWOOTIV GNOdW) ueTo}IS ST Teuueyo oy AO (OIWOGY) peTseouRDS ST 4T 

Jt (GHLYOdW YYHOI) ToIZe ue suinjet ALIUM CWO ~(HSWeqTIm eoT) obessou 

@3TIM 34} set{del aLIUM CWO ‘Jes ST BbeT} AOWSSAWALIUM AOIGW eu 

Jt pue ’(potieq eot) potized pue (eumToA eoTt) sumToA speoT ALIYM CWO 

‘jas St beT} IOAUNd JOIGW Ou JT /sqreqs ATTeN}Oe |24TIM |YyQ USUM 

*(dOLS GWO) peddojs st [Touueyo oy} Jt AO ssorzbord UT 34TIM Toeyjoue 

ST o1eu} JT sqsenberz dn sonenb gqLIYM GNO ~‘(NOILWOOTIVON dadsOraw) 

Ioize ue sum }zer At ‘/astTMi{ayjoO /Teuueyo paRoeTes oyj butsn punos 

e skejtd @LIUM AWO ’}0eTI00 st (ABdyOOTTW eoT) Aay UOTJeEDOTTe 9YW JI 

-(4Tuq OT) Teuueyo otpne aTbuts e Toy pueumiod prepuejs e ST ALIYM CWO 
NOTBLONNA 


‘pepeoT aq jou Aew (yuybueT eot) yQbueT pue (ejeqd eOT) yutod Azjuse O/I Tewrou —— ALIYM GWO 
ZJajuTod ejep Meu ay} IO He{jJ IOAUAd JOIGW ey} es ysnu nod /dzTIM AWWN 
snotaeid e butddoqs zeqye ATa\eTpoumIT 93TIM 9yR SszTeIS ALIUM GWO JI 
sond ALIYM GWO/OlUTSag/eoTAap ‘ otpne 


16 


*pouzojied ATTenjoe st ebundxg oy} ’asn ut AehuoT ou To ‘asn uT OU 

ST S0TAep oy} UeYyM ‘petTTejep oq 03 ebundxg ayy ssned TTTM ’o1ezZ—-uUOU 
buteq zUuNoD uaedo aotaap ayy Aq peUuTUTajep se ‘sdTASp sy, JO sresn 
Teyjo Aue Jo aouaysTxe syL ‘“‘peasoons [TT suedo meu OU OS ‘/4STT s0TAep 
eu} WOIJ peaocuReI useq ApeaertTe sey soOTASep oy ‘peTTeoO ST TI oUTz oy 

Aq ‘[Teo aoTasquey e SeNssT Jesn e USsYyM peTTeoO sT oeuTANnoI ebundxg aul 


NOIDLONN 


SOTASp OTpNY ey} SAOUST OF SAITSOp e o}eOTpPUT — ADNNdxXd 


abundxg/aotaap ‘otpne 


O1aeZ O} Jos — 4tuq OT 


T- 03 jes — DOTASq OT 
(OTpnYOI 3ONT4S) YyooTq ysenber oTpne 0} Ae\quTod —- ysenbeyotT 
SLNdLNO 
SToeuureyo serj 03 pesn /Aay uoTRedDOTTe —AdYyooTTW eOT 
(€ ny O STeUUeYS O03 puOodserTOS ¢ NIA 
0 S31q) (Saud GWodw) serTjJ 03 STeuUReYyo jo deui 4Tq —- 3tTuQ OT 
(aotaequedo) uedo (Aq yes YooTq O/I wory petdoo 
Io) Aq yes oq ASsnu ‘aepou soTAap Of AaqQuTOd — QoTAed OT 
(OTpnyOI 3OnI3S) YyOoTq Aysenber oTpne of AaqUTOd — qsanbeyot 
SLAdNI 
*pebundxa 


ST a0TAep eyQ ‘/butpued st (ebundxq) oebundxe ue pue oO1ez OF STTeF AT 

Jt pue /3unod Usedo aU SqUeUeADep soTASgeSOTD “weyuy (agud GWodw) seerz 
aoTAedesoto /(AeyooTTw eot) Aaeyx uoTReoOTTe Swes SY YFTM pezeooTTe 
STeuueyo Aue ere ereyy JI ~*(a0tTaeg OT) AequTOd sdTAap syy sieato 

pue (OTpnyol) YOoTq ysenber otpne O/I ue saye} ZI ‘pesn aq Tebuot 

OU T[TM 3T 3eY} SOTASP OTpNe 9YyQ SeTJTIOU SUTANOI BSdOTASGeSOCTD SUL 


NOI LOND 
TW 
/ (qsenbeayoT ) a0 TASadasoTD 
SISdONAS 


SOTASep OTpne ey} 0} SSseodode azeUTWMIAR -— SdTASeSOTO 
AWWN 


BOTASGSSOTD/S20 TAaep ‘oTpne 


17 


ALIYM/20 TAep 


ALWVGdN/20TAap * 
LASAY/20TASP * 
CWaY/20TASPp ° 
LSOd/20 TAS * 

ao TAaquadO/a0TAap * 
FONNdX/20 TASp * 
GIALIYMdI'TO/e0TAap ° 
CIGWAUdITO/e20TAap ° 


BOTASQeSOTD/a0 TAep 


Ol UTbag/a0TAap* 


‘preoqdtTo 
preoqdt To 
pieoqdt To 
pieoqdTTo 
preoqdtT To 
pzeoqdt To 
preogdt To 
p1reoqdt To 
preoqgdt To 
*preoqdtto 
pzeoqdt To 


sjua\U0D 


zoriq ot jo Adoo — ro1l1a 
speeo0ons aotaaquado Jt /Aaey uotzeooTTe enbtun —Asyoo [Tw eot 
uedo ou ‘/paTTey uoT}eOOTTe — GATIVAOOTIV YuaOIdY 


peTtey uedo — TIWANSdO YAOI 
JOII9 ou — 0 
:Jaqunu TOTS — IOIIG OT 


Q aSTmMTayjO ‘UOT eOOTTe 
Jt (¢€ nzyA CO STeuUeYo OF pucdsseTIOS ¢€ NIA OC 


S}Iq) STeuueyo pezeooTTe AT[njJssaeoons jo dew Iq — ytun OT 
[- eSTMTeyjO 
‘speecoons adtaequado JT apou aotaap oj AequTOd — edTAed OT 
(OTPpNYOI 30ONn73s) YyOoTC ysenber oTpne of Zajutod — ysonbeyot 
S.LNdLNO 
posn jou — sbeTj 


UOTIROOTTe OU TOF oEz ‘(9T NIYQ QO) 
Kerze uotjdo uotjzeutTquoo Teuueyo ayy jo yybuetT — YyQbuey eoTt 
(yqbueT 
Olez—uoU) UCTIeDOTTe ATOZ Aressaoou ATuo /(E nazyA 
0 S[TeuueYyo 03 puodserrI0OD ¢ nay} Co satq ‘AerIe 
ajAq) suot3do uotzeuTquios TeuueYyoS Oj TequUTOd — ejzeqd Pot 
(y3bueT orez—uou) uoTReoOTTe AOy ATessaeooUu 
A[uo ‘uotzeooTTe Toy yIOd abessou 0} 1aequtod —z1o0dATdey uu 
(yujbueT orez—uou) uotT}esoTTe r0J ATeSssedeU 
Ajuo ‘(/ZT nu} gz[—) aeouspecerzd uot}eooTTe —- Tid UT 
(OTpnYOI }ONTAS) YOoTq ysenber otpne 0} TequTod - 3senbayot 
pesn jou —Tequnn>zrun 
SLAdGNI 


‘Iq TeubTs peqzeooTTe ue yQtm (zrogdTdey uw) rod ATdar 

pezttetztut ATizedoid e serztnber ostTe aotaaquedo ‘sTeuuryo 9s zedOTTe 

OL ‘STTe} 4T JT a0TAep oOTpne ayQ (aoTaaeqeso[TD) saso[o puke pesoons 

0} UOT}VOOTTe OJ 3TeM YOU Seop aeoTAequedo =~ (GHTIVIOOTTW YYFOIAW) 

qoiia ue summer aotaaquedo ‘astmzeyjo /(4TuUN BOT) pTEeTF 3tTun sayy 

OUT pepeoT ST uOoTReUTqUIOO ToeUUReYO pa}eoOoTTe ey ‘Spesdons UOT ROOCTTe 

aut JI *(ezeqd Rot) suotjdo uoT}eUuTquoo TeuUuRYyo jo Aerize e WWI] 

STeuuryo oTpne (ALWOOTTIWV GWOdW) a3eOOTTR OF SaeTry aotasquedo /orez—uOU 

ST (ujbueT vot) yybueT ey3 JI ~*(ebundxqg) pebundxe buteq worj soTAap 

au} butdaey jyunoD uedo ay} sjzUeUWeTOUT soTaequedo §*(TIVANAdO wugO!) 

roiza ue summjer AT ‘astmreyjo /(AsyooT TW eotT) Aeyx UOTPROOTTe 

au. pue (a0TAeqd OT) ZaquTod soTAap ay} SpeoT 4T “a0TAap OTpne otf 

uedo A[[nJssaoons ued AT JT pue /(ysenbseyot) YyooTq 4sonber otpne O/I 

ue soye} JI ‘aoTAap OTpne ayy 0} SSedoDe sqUeIb eUTINOT adTASqUedO eUL 
NOIDLONNd 


‘(sbeTjJ ‘yzsenbeyot /‘rTequnnztun / ,QOTASp ‘OTpne,, PoTAaequedoO = IOI 
SISdONAS 


aoTAep OTpne oyj uedo — aoTaequedo 
AWWN 


aoTAaquedo/a0TAap ‘ oTpne 


18 


"pasn oq ZTebuoT ou T[[ts ysenbeyot 
aU} 3eY} V<oOTASpP pXeOqdTTO ey} SeTFTJOU SUTANOT STUL 
NOTLONNA 


(3senbeyoT )a0TASeqesoTD 
SISdONAS 


aoTasp preogdT{[oO ey} OF SSaDoe |ReUTUIE} — sdTAEdeSOCTO 
AWWN 


BSOTO/ae0TAap' preoqdtTo 


-()oIod pue ()OIpues suotjouny AreIqTT 

oexq ou} PTA IO ATRO@ITp peTTeo oq ued FI “Spueunlloo soTASp 

SLTIIUT OF pesn UOTJOUNJ soTAEep SsTOYAIOM eyy ST Ol UTbeg 
NOIDLONNA 


(3senbexYot ) o10d 
(3zsenbeyot ) oI pues 
SISdONAS 


OI aoTAep preoqdtTo o}zeTRzTUT — ol[uUTbeg 
AWN 


O[UTbag/aoTaap * preoqdT To 


19 


yes ST 99TIM QUaTIMS ayy JO CIdTTID euy aIdt{D OT 
GIGLIYMdITD CWO pueuog OT 
aotaequedo Aq jeseid qtun OT 
eotTAaequedo Aq yesard aoTAed OT 
dn yes yogATdey uu abessayW OT 
LSGNOAY OI 
“petystTzes oq 


Iaaou pseu pue azeTosqo st ysod ayy /TaTJTQUepT 3sod ayy 

uey} ra}eerb JT :pueumioo ysod e Jo ey} YIM perteduioo oq ued 

2eUu AaTjTzUepT dTTO e yyTM GIdTTIO OT eUuy STTTJ GISLIYMdITO 
NOTLLONNA 


ASTI TIUSPT 3FTIM BUETANS sy sUTUIAZEp — CIGLIYMdITO 
GWYN 


CIALIMMdITIO/a0TAap ‘ preoqdT To 


B - 20 


yas ST O3TIM QUaTIND 3syW JO aIdt{D ey4 GIdt{D OT 
CIqwaudITO GWO pueuloD OT 
aotaaequedo Aq jyeseird 3tTuq OT 
aotaequedo Aq yeseid BoTAeqd OT 
dn jas yz0gA{Tdey uu abessay OT 
LSaNOdY OI 


‘Hutyzsed umo S}T TOF pTTea OU ST uoTjeoT Tdde 

ue Aq ATazeataid ptTey ezep ysod oyR ‘TETJTzUSepT 3sod au 

ueyu} Tezeetbh JT <:pueumiod ysod e Jo 7eYU} YFTA poreduod oq ued 

qeuj TeTjTIUepT dIToO e YyIM CIGTTO OF ey} STITF AIGWaYdITO 
NOLDLONNA 


ASTJTUSpT peat yUeTIMS sy suTuejep — AIdwdddI'lO 
dAWN 


CIdWaudI'IO/a0TAap " preoqdt To 


‘pT[TeA Jou st ysenbeyot eyj pue y4[nsez 
oi9az-—uoU e suIN}eT ‘/[N]Jssaodonsun sem uedo syy jI 
SLINSHY 


"popssu TsbuocT OU ST adTAap sy} OF SSad0e USYM [TRO 
()aoTasdesotTD e Aq payojeul oq 4snul [Teo ()aoTAaquedO [NJsseoons VY 


“(*°* / a0Taep’ preoqdTT—d,, )eoTaequedo }xeu |eYyz TT}UN ‘-9°T) pepecou 3xou 

"3TUuQ OT pue adTAad OT [Ttjun Aztouwu worTjJ peaou!r ST soTASp pieoqdtto eyL “s3tun uado 

7UT PETTITTE oq TITM Fey? YOoTC ysoenbeyot ey} UT spTeTy ou Sey sdTAep preoddTTo ey} pue ‘/soTAep pxreoqdTToO ay} Aq pesn 

OM} OTe STBYUL ‘“SOTASpP eB OF SSad0de SqUPIb SsUTANOT UsdO SUL Azowoul oy speeu ueysAs oyj UsYyM peTTeo ST suTynor ebundxq ou 
NOILONNA NOT DLONN 

(9 ‘asenbeyot ’31uN /,,a0TAep’ preCgdTT{)d,, )eoTAsquaedoO ¢sueabord uot}zeottdde Aq peTTeo ATTereueb you st ebundxg> 
SISdONAS SISdONAS 

2dTASp preoqdt{To ey uedo — sdtaequedo aoTAep peoqdT[O ay} SACU OF SITSEep e szeoTpUT — obundxq 
AWN AWN 


30 TAaquedo/ao Taap * preoqdt To AONNdXg/a0 TASp " preogdT To 


B- 21 


Speorl juenbesqns Aojy 1934Te 


jou Op :peer sty} oF poubtsse q]I dt[o ayy GIdt{o oT 
yybue]T OT =; TenyJow OT JT Jog puockeq 
ST YoTYyM /UOT}ISOd pear 4x9U OF pe jepdn ZESJFO OT 


(ezep Jo saqzAq Tenjoy OT sey MOU AazTjnq ay) eqeq oT 


peer saqzAq Jo Aequmu Ten joe ou YATM PeTTT} Tenqow oT 
pezrindsso 1OATS ue JT O1ez—uOU IOIIYG OT 
SLTNSAY 
peel [eT}TUT ay} ST STYR JT OC1EZ dIdtTo of 
peer 0} eRep Jo yesjjo a7Aq ZOESJFO OT 
e}Zep Teao dtyxs 
0} [[Tnu IO ‘T[T}J OF eRzep Jo AaezjJnq 03 AaqQuUTOd eqeqd OT 
Iajyjnq ejyep ut 3nd 03 saqQdq Jo ASequmu uqbueT OT 
davau dWo pueuluod OT 
aotaequedo Aq yeseid 3tuq OT 


BoTAed OT 
obessopf OT 


eotaequedo Aq jeserd 
dn jes 410gATdey uu 


LSanodd Ol 


“pozertytut oq mou Aeul suotjZersdo asoyy Fey Se zeOTpPUT STTJF Jo 
pue ouj ysed peer styuL ‘“JJO pTey ore preoqdt{[o ey OF e3ep 
MoU 33TIM 03 Sqdueqze Aue ‘dtTo e butpeazr Jo o[pptu ayy UT ST 
uoT}eot{dde ue aTtyum zeuR erzeme og ‘“dTToO sty} butpeer ybnoryy 
ST uoT}eoTTdde ayy zeU} SOTAepP pIeOqdTToO ay OF TeUbTS 

e se sqoe sty} ‘dtTo ayy Jo pue ayy puokeq ST jesjjO OT UeyM 


‘ujbueyT ot ebny e butsn Aq 

@STTjJ-jo—pus syy oj Hbutddtys AoJ [njJosn st sty, “peer useq pey 
soyAq yjbueyT oT JT se Tenqow ot Aq pajUueUeTOUT ST Jesjjo OT 
ueyy ‘/T[nNu st ejed OT JI ‘spear quanbesqns AOJ peyono jun 4T 
HUTARAT Ue ‘peer 4SITJ aU OJ OTEZ 0} YeSFjJO OT HutzWes Aq 
peaetyoe st ditto ey4 jo butuutbeq ayy worjy ssaooe TeTj}Uenbes 
[RUION “peor STU} ACJ poubtsse dI ayy YTM peTTT}y oq TIT 
yotum ‘GIdT[O OT O1ez e aaey pTNoys ysoenber peer 4sAaTty ous 
‘pieoqdt[o ey} WoTy eIep UQIM PETIT} ST eyed OT pue ‘/ysenber 
pear [Teulrlou e se sjoe YT /dTToO ayy UTYQIM ST JeSJJO OT USYyM 


*sasodind om} saeazes uoTIOUNS peer sul 


NOILONNa 


pieoqdt{o wortj dt{To peer — avau 


AWau/e0TAap* preoqdt To 


GWYN 


peTystqes ST STY} JT pueuMlcd o4TIM ayy UT 


pesn aq 03 /3S0d sty} 03 peubtsse dI dTtTo oyy GIdtTD oT 
perindsso0 IoIISN ue JT OezZ—uOoU TOIIG OT 
SLINSAY 
O19Z GIdt[TD ot 
310d obessou AJst}Zes 0} AsQuUTOd eyed OT 
LSOd ddd pueuwlod OT 
eotasquedo Aq jeserd 3tun OT 


aotTaequedg Aq joeseid 
dn jes ZIogATday uu 


BoTAed OT 
abessop OT 


LSANOY OI 


“{sod ayy AyJstyZes OF pssU OU ST 

ereuy ‘/TezeetIh st GIALIUMdIID JI “puewwoo CIaALIYMdITO 

ayy Aq pournjer yey} YFTM CIGT[IO OT s,y4sod ay} Yyoayo 

plnoys 31 ‘(sztxe 4T eTojeq ‘*H*a) 4T AjsTQes pTnoys 3T JT 
SUTULTajep OF SeysTM pue y4sod bhutpued e sey uoT}eoT{Tdde ue J] 


‘juazINd 
TIT#S Jou st dTtToO syQ ‘TezeeIH st GIdWHYdITIO JI ~*pureuaco 
GIGWIUdITO ayy Aq pourINzer zeYR YIM CIdT[D OT s,}zsSod 
au} yooayD pTnoys 3T /dTtToO jueTmMod ayy TITAS ST pouwrojyied 
sey 31 3sod e JT oUuTUIa}ep OF SaYSsTm uoT}eoTTdde sey FI 


*peqdniziz0o 

jou sT 370d ey} 3eY} OS 310d abhessoul AjJstjes sy} WOTJ PoAoUleI 
aq ATTenjoe Ysnu os pue ‘sedTAep preoqdT{[oO ayy Aq pesn—o1r 

aq ueyy Aeul WT :poaAtToeoar useeq sey ebessoul oy} }eY SezeOTpUT 
dt[To oy} buTRTIM Jo Qoe syL ~‘“pewrojiszed eq ysnu 4sod oeyy 
UJIM pezetToosse o3TIM |y} ‘paeATeder sT ebessou AJstTjes oyy jI 


‘perltnber st ejep ayq JI abessoul 

AJst}es e pues T[TM soTAep preoqdT{oO ayy YoTYM 03 Wiod abessou 
e soptaoid ysod ey, *3T Ssjuem ucTeOTTdde Tey}oue sseTuN 
pieogdt{[o ay} OF 3T HUTRTIM pue WIOJ JdI ue OF FT but zreaUOD 
ptoae 0} osues sexyeul snyjy 4t pue ‘ATjuenbery HutTbueyo 

zo/pue ‘/jeuoJ eRep ajeatid e UT ‘abIeT ST yNdod e USsYyM pesn 

aq O} pepuajUuT ST STYUL ‘“paeoqdt{o ay} Jo sxossaooe Aq asn 

IOJ aeTqe{TTeae ST ejzep ey SOTASP pXeOQqdTTO sy} OF SzeOTPUI 


NOI LONNA 


pieogdtTo 03 dtTo ysod - Lsod 


LSOd/20TAaep* pre0CgqdT To 


SWWN 


22 


pezmMooo TJOILTS ue JT OA9zZ—uUoOU 


@4Tim ey} JO dIdTTO ayy 
aLWddn CWO 

aotasequedo Aq jeseird 
aotaequedo Aq jAoseid 

dn yes qyrogATdey uw 


ATorIIg OT 
SLINSdAY 


dIdtTO OT 
pueuloD OT 
yun OT 
aoTAed OT 
abessapl OT 
LSanoau Ol 


*butpued 


aie spueuoo 331T1M 3eyQ jo Aue oTTYyM penssT oq jyoUuUeD puUeUROO 
STuL ‘(speaz) saqysed Hbutpued Aue oJ pesn oq ued pue ajeTduoo 
aie spueumlod 34TIM snotaeid eyQ 7eUuy preOgdTTO 9Yy OF Z}zROTpUI 


NOILONNA 


pieoqdt{To ay OF 43NDdD e Jo Hbut3ztI7M ay ezeUuTUA - aLVddN 


AWWN 


qLwddn/sotaep* preoqdT To 


atTqtssod st O/I yotnb JT 4S WOINO AOI 
Lasay dWo 

sotaequedo Aq josead 

dn yes yWogATdey uu 


B - 23 


sbe[q OT 
PUPURUIOD OT 
a0TASed OT 
obessow OT 
LSanOdY OI 


‘20TASp uado ou OF 
SeTpuey butTAor}sep yNoyuATA soTASp preOddTTO ey W syzeseYy 


NOTLONNA 


pireoqdt{To ayy eset — LasSaY 


GAWN 


LaSaY/eoTaep * preoqdT To 


3} TIM/S0TASp * 
*a[TOsuoo 
*aTosuoo 
*aTOsuoo 
*aTosuoo 
*aTOsUuOoD 


pesy/a0Taap 
qraauopAeyaney/a0 TAep 
a0 TAaquaedC/ad TAep 
IeajToO/aotaep 
dewkey.eSdo/ae0TAep 


JeTpueyyndulqo/eotaap* 
*aTOsUuoOD 


dewAeyyswdo/eoTaep 


aTOsUuOCO 


aTOsuoo 


$]ua U0D 


SOqTIM YUenbesqns AOJ TazTe 


jou Op :ea3TIM STY} 0} poubtsse dI dTToO ey} dIdt{o oT 
uOTATSOd 23TIM }x9EU OF pa jzepdn #8SJJO OT 
u934TIM seqyAq Jo Tequnu Tenjoe ayy YITM PETTTF Tenqow OT 
perandoso IoiZa ue FT OLezZ—uOoU IOIIG OT 
SLTNSAY 
qysod e Ajstzes 0} ST STU JT 350d oF 
JO GIGTTD ‘aTIM TeTITUT OY ST STUUR JT O19Z GIdt{[D OT 
OUTIM TeTITUT ayQ ST STYQ JT OTaez ATTeNsn JESFJO OT 
O}TAM OF eReP JO YOOTq 0} Tajutod eyed OT 
O}TIM OF PREC OT WOT saqzAq Jo Tequmu yybuey] OT 
ALIYM CANO pueulloD OT 
eoTaequedo Aq jeseid 4rIun OT 
aotaequedg Aq jeserd BoTAed OT 
dn joes yIOGATdey uu abessay OT 
LSanogu OI 


‘GIdTTD OF ay} T0zTe 

jou Asnu saqytTim jYuenbesqng ‘azTIM 4YSATJ eyy IOJ GIdTTD OT 
ou} HbutreetTo Aq peuTeqyqo ST qI meu e ‘fasTMIsy;O ‘“pesn 3q 
3snu pueumoo 4sog ayy Aq peuInqer GIdTTO OT ayy ‘ysSod 
Hutpued e Toy HsWAjstjzes e 03 asucdsel UT ST 99TIM STU FI 


“sole8Z UJTM pepped st dijo ayy ‘azts dTtTo 

quezimo ay} puokeq Taae Sst JesjjO OT JI ‘*SezTIm Juonbesqns 
IOJ pera}Teun oenTea pejueweroOUT oy Hbutsn pue ‘3 TIM 

TeTRIUT JY} OJ YesyyJo OT Hutrzeato Aq ATTetjuenbes pepTaoiad 
eq ued eRep STUL ‘“pzeOoqdT[O ayy OF ejJep SeqTIM pueuMOD STUL 


NOIDLONNA 


preoqdt{o 03 dtTO e3TIM — ALIYM 


FLIYM/20TAap * preoqdt To 


GAWN 


B - 24 


*IOPOSA 
AzqeiqiT eyy se ysenbsyot eyz JO 3NO PTET} soTaed OT 9yy 
qeib uey} pue (9 ‘ysenbeyot /T- /,,ea0TA@p*eTOsuUOD,, )soTAsquedo 
0 ST adTAapP aTOsUOD ay} AOZ [Teo ,ATerzqt usedo, euL 
-s10}00n AIeIQIT SoTAAap aTosuod ay} UT UOTJOUNF e ST FT FeYR 
UT SpueUMIOD BdTASP prepuejsS WOT} YUSTeFFTIP ST uot JouNF STYL 
SaLON 


"yseq-qndut wou 
ayy AT Tensn st yoTuM /Teonpord ayy wory squeAs ynduT sydaooy 


NOLLONNA 
TW OV 
(aaqgeTosuos /sjuaAd) TeTpueHyNndulqdo 
SISdONAS 


BoTAep STOSUCD ay} IOJ YUeAS YnduT ue eTpueYy - ATeTpueHynduldo 
AWN 


JeTpuepyyNnduldd/seo asp ‘aTosuoco 


-deu ADY QUeTIMO 3Yyy UGTA WLW OI Fe eany_oNzTAS 3Yyz 
STIT} pue ‘qsenbayot ey} UT pTeTF ACATS ey Ses UOT JoOUNyZ STUL 


‘uoTSIeauoD weer3s azhq OF 

apookey MPI ay} eqtiosep 0} sprombuocT 3YbTe 
deyAoyx dewAey ons 

(dewAoyx ) JOOZTS 

olaz asta ‘atqtssed O/I yotnb Jt woInd AOI 
dWWAAYMSW dd 

aoTaaquado 03 [Teo ey Aq yosead 

aoTaequedo 03 [Teo ayy Aq jYoserd 

aTqtssod jou st O/I yotnb jt yes yrogATdoey uw 


SLTNSAY 


e}zeq OT 
yzbueT OT 
sbeTaq OT 
pueulliog OT 
tun OT 
BoTAed OT 
abessoyW OT 
LSANOdY OL 


-3Tun eTosuco sty Aq asn 
UT ammjonzys dewAsy JueTINS ey} YFTAM Aezjnq WLVd OI ey} STITd 


NOTLONNA 


aTOsuCO STYy} TOF ernjon13s dew Asx yZUeTIMS 3y4 qoeb — dewAoyysyv 


GWYN 


dewAeyySydo/ae0TAep *aToOsuoo 


B - 25 


atTqtssod st O/I yotnb JT Jes WOINO AOI sbeTd OT 

YWETO GWO puewwoD OT 

aoTaequedo 03 [Teo au Aq yoesemd ytun OT 

aotaequedo 03 [TRO ayW Aq yesaid BOTAed OT 

aTqtssod zou st O/I yoTNb Jt yes Wogd{dey uu abessoy OT 
LSANOFY OI 


*sjsonber peor 
AJstqes 03 bHutqytem sqzroder Aue Jayznq yndut oy} worj saocupy 
NOILONNA 


Iajjnq yndut eTosuoos reaTO — 7TeaT{oO 
GWYN 


IP9TD/a0TAap ‘aTOsuoD 


‘YLVd OI wory dew Ady jUueTIMO sty 
STIT] pue ysenbeyot eyy UT pTeTJ TOIT sy sjes uoTIoOUNI STUL 


SLINSAY 
‘uoTSZ@eAUOD wearjs ajhq 07 
apookeay MeI ay} eqTIOSep ey} sproMbucT qybTe 
dewAoyx dewAey 3on1r4s eyzeq OT 
(dewAo ys ) JOOZTS yjbueT OT 
olaz asta ‘atqtssod O/I yotnb jt YOINO AOI sbheTq OT 
dWWAGMLES do pueulioD OT 
aotaequedg 03 [Teo ayy Aq qosoid qtun OT 
aotTaaequedg 0} [Teo ayy Aq zoserd BOTAN OT 
aTqtssod jou st O/I yotnb FT Aes qiogATdey uw ebessayy OT 
LSGnNOdd OI 


wLwd o1 Aq 0} pequtod aamjoniz4s ayy 
0} 3TuUN aTosuoo styuy Aq pesn eI oONITAS dewAoy WUeTIMD 9ayQ Ss3zeS 
NOT LONNA 


aTosuoOD stu TOF eammjonzys deu Asx JUeTINO 3yy es — dewAosy.eSs 
AWWN 


dewAey.eSdo/s0 TAap *aTOSUuoD 


B - 26 


*IOWOSA 
Areiqt{T ay3 se ysenbayor eyy JO 4NO PTeT] soTaed OT 3yy 
qeib uey} pue ‘(9 ‘ysanbayot ‘T[- /,,a0TAep' eTosuod,, )aeoTaequedo 
©} ST SOTAap aTOsuOD |Yy} AOJ [Teo ,,ATerqtquedo,, ouL 
‘sz0q00eA ATCAIQTIT SoTAep STOsuOoS ayy UT UOT JOUNJ e ST 4T 3eUR 
UT SpURUIOD SOTASP pIepuejS WOTJ WUSeTSJJIp ST uoT}JOUNJ sTuL 
SaLON 


"PITRA |Te Aeyjnq ey} UT sTajZoOeTeYO sy} JO [Te ION 
‘paqoajep Sem UOTRIPUOCD MOTJABAO AaTjnq e ‘T- ST Tenjoe jT 
Suoudd 


"Ind00 OF YNOGe SeM MOTJTSAO Taeyjnq e 
JT [- to ‘/Zaejyjnq oy UT sTaZOeTRYO Jo Jequmu 9yy — TeNnjoe 
SLINSdY 


‘SOTAep STOSUOCD ay} JO dsdTASed OT |YyW - ABdeTOSUOCD 
‘pesn oq 03 st deu Ady SsOTASp aTosuCD 
}INejep ey JT [Tnu Ao ‘Aajutod sanjonzys depwhsy e — dewhoyx 
*-saqhq UT azts Aayjnq ey} ‘a°t ‘uoTRZedtoTjUuUe umUTXeW — YQHUaeT 
“uOoTSIeAUCD SsTuy Aq po}eTSUeh sisqjoPTeYO 
pezedtotjzue [Te pToy o3 ybnous ebrzel{ Aayjnq a3Aq e - Aaejjnq 
‘TayutTod sanjonzAS Auseagqgnduy ue — juUaAD 
SLAdNI 


"Layjnq sayy OUT 4[NserT sy saoe td 
pue ‘dewAey ey} uo peseq ‘soqjAq ISNW 03 AGMMWY SSWIOdI 
odAj JO squead Andut szZeAUCD UOTROUNJ |Tosuoo sTYyL 


NOI DONNA 
OV cW Td TW OW od 
AaqdetTosuos /(dewkey ‘yqbueT /rayjnq /‘juUaAde)ATeAUODADYyMeY = TenN}oe 
SISdONAS 


SOSSe[O AyNndUuT MeI apoodap — TeAUODASyMeY 
GWYN 


PIBAUODAVYMeY/2OTASP * 9TOSUOD 


“puewWoOS O3TIM 
buTpuejsyno ue St eTey} Teaoueym eTosuod eyy 
Aq asn ut AjtjTetquajzod st MopuTm sty} FO 71Ody 
ouUL *(eaoqe aes) OQ ST TTeO sotaequedo eyy 
uT 3TUN eYyZ JT pettddns eq ysnul yI = “eToOsUOCO 

stu} 1OJ pesn oq TTTM 7eYF MOPUTM SYA ST STUL _ 
MOPUTMy MOPUTM 30Nn74S eed OT 
LSanodd OI 


‘siequmu 3tuN pTTea Ty AO 

OU ae eTOUL ‘“seoTASep ay} UeYy} TeyHTY [TeaeT eB Fe SsUOp eq 4SnU 
ajTosuos e burzreys ‘aTosuod enbtun e OF MOpUTmM pettddns sayy 
sputq o7ez Jo 4tIun WY “TOJeA ATeIqTT sdTASP 94 OF 1ajutod 

e 3ab 03 pesn sT sty} ‘/peuedo oq OF ST eTOSUOD TeN joe OU 

yeu} SajeoTpuT T- JO }Tun Y ‘“eoTASep STUA Aq Ajt{etoeds pesn st 
[Teo uedo ue 10jy AJajzoureted prepuejs e ST Fey} ToquMU 4TUN SUL 


*3ynd3no TOF sdTASp 
aTosuoo ey} Aq pesn sT 2eY4} MOPUTM S44 settddns uot }eulojyut 
UOTIEZTTLTRIUT STYUL ~“YOOTC ysenbeyoT ey} JO PTETF WLVd OI 
au UT petTTddns oq 0} UOT eULIOJUT sulos saitnber 4T Fey UT 

spueulioo uedo adTAep Tay}O SOU WOTJ STeFFTpP pueuwlico uado sTuL 


‘pTeTty LINA O1 ey ATqtssod pue PTT} AOIAKC OI 

ay} «UT peTITy eq Aeu ZeyR YOoT ysonbeyoTt ayy UT SpPTeTF 

OM} 91e osIDUL “90 TASP e OF SSa00R squerb ouTyNnor uado SOUL 
NOI LONN 


(9 ‘asenbeyot /4Tun /,,a0TAap’ aTOSUOD,, )eoTAsquedo 
SISdONAS 


BoTAep aTosuoo e usedo 0} ysenber e - 20TAequedo 
dWWN 


BoTAequaedO/a0 TAap ‘ aTOSUOD 


r~ 
N 
~O 


GayvWMMOVd YwoOsuUNO dno aT 


dayvMyoOd YyosynNo ANo OT 

NMOd wosHnNoO dno aT 

dn wosdno nno UT 

YALOWYVHO LYHSNI- Hol DT 

uOoTATUTJeqd Suen )osa 

‘suofTootues Aq peyeiedes ore sXojourered OTToumMN ‘SiAdjoureIed oTTEUuMU 
JO Zequmu Aue ST ,¢,, '.'6/P1I, ‘'b'a ‘/saeqowered oTreumu 

OM} ST un ‘Iojouered oTTeumu [euoctj#do ue ST ,T, :Ssreqowered 


yqtm (josqg Io g6$ /*a't ‘Iso Aq peonporquT) seouenbas [or}UCD 


ALWLS IVWILINI OL “LHSde slay o 

(JazeT peqyroddns seq jou [TTM) LdNyygaLNI LNI e 
UOT}TUTJOqd SUIeN osq 

—_— (osq Aq peonporjzuTt) seouenbes edeosq eTqrtzeduioo—osI 


3STT }XeU 98S -YAONGOUMINI BAONANOAS IOWLINOO ISO ] TT/60 
>XHQNI SSUMANY IY WW €ET/8O 
-GNIT LXSN ISN 9 G /80 

d 


SUTT SUC UMOpP uoT3tTsod SAT IOS SYA SACU -XHAGNI ANI y /80 STTtj pue ‘ysonbeyot 2uQ UT PTeTJ AOAAS 9Yy Syoes uoTyouNF STUL 
Bape gop es fet er, RS ASG yet ee ee ea eee een ees Cee ge Re SWINSdd 
UOTITUTJOd SUeN OSY TO BpoD 
‘pzreoqhey oy} wor 
Adwosa Sq TT/T0 peat 03 STayoereyo ey} AOJ uoTReUT Sep SUL 
NI LAIHS Is ST/00 [ed ING Ae ezed OF 
LNO LAIHS OS 1/00 (Tends) Joozts yybueT ot 
NUNLAY FOWIMUWO Ww ~£€1/00 o1ez este ‘atqtssod O/I yoTNb FF AOINO AOI sbeTd OT 
aaqad Wuod ai 21/00 Cvdad CWO DaPN Ot 
GvL IWDILLMAA LA I1/00 aoTaequedo 03 [Teo ey Aq jeserd 4tun OT 
Gaga ANI ay OT/00 aoTaequedo 0} [Teo auy Aq joeseid BJOTASd OT 
IOVdSYOW Sq g /00 aTqtssod jou st O/I yotnb JT jes q310gATday uw abessopW OT 
pet chet te gyi ae ao eh es ts ee ce en Ts ae ee, et rare LSANOFAY OI 
uoTRTUT Jad oureNn BpoD 


—— (ZaeoNporTUT oU) sUOTROUNY TOT}UOD WUSepUedepuUr 


‘peer saqzAq Jo Tequmu 93yy YqIA 
IWALOW OI pue ‘/4ndut 3xeu ey} YIM Pere WIWVd OI ysenboyoTt ey 


“aTqetTteae ATAUeAANS 


yndut ey} UTM peTjstTzes eq T[TM ysoenber ay} ‘HLONAT OI TITS 
ueo se yonu se jou ynq ‘ynduTt sulos Sst say} JT ‘petjstzes 


28 


B 


daLY¥OddNs SHdOD ISNWV 
oq OU TITM pueuMmioo sty} ‘yndut Hutpued ou st ereYy. JI 
‘Q0TASP STOSuOD ay 

©} 83TIM 0} 3X9} ISNW eUuy BbuTUTejUOCD Tayjnqg e b¢spuoodesoro Up / <spuodas> /0/0/<¢stetytTenb> ‘ <apoohey> ‘0 /T<ISo> 

[]zeyjnq zeus eyed OT -WwIOJ Sy UT /FTESzT JUSAS YndUT oeYW 

(ray jnqx ) Joezts yqbueT OT WOTJ UOCT}eULIOJUT Say} YITM SztIodaz apookey me uINjeT prTnom 

ojez asta ‘atqtssod O/1I yoOTNb JT yond AOL sbheTq OT sexy ‘(]osg 10 g6$ ST <ISD> eTeyM) aTOsuodD 9Yy} OF ST<ISoO»> 

ALIYM AWO pueullog OT 6utytim Aq peTqeue useq pey sapooAey mer ‘oTdurexe AOjJ ‘FTI 

asoTAaquadg 0} [Teo ayy Aq Aoesaad 3tun OT 

aoTaaquedo 03 [Teo ayy Aq yasead SOTASd OT dewhoyjzes pue dewAoyysy yytM 

eTqtssod jou st O/I yotnb JT yes yrogATdey uw abessop OT peTjtTpoul ST yOTYM ‘TUN 94 YATM pejzetToosse deuoy oy} PTA 

LSINOAN OI peqyeauoo are skoy *(pueumliod a4TIM ey} 9es) seouenbes [TO13UOD 

quy pue qyS eu} eTA pereq [Ty ATeATJOeTes eq Ukd SdTASp aTOSUOD 

-hutpued ay Aq paatacer sqjueae ynduTt mey “seouenbes [or}UCD IO 

ST puewlod 33TIM STUY} STTUM 92Sn UT ST MOPUTM STOSUOD sy 3X89 «IIOSW TeyRTe ‘/*a°T ‘weerqs a3A4q ISNW Ue se ST 4nduUT sTYA 

JO RIOgY ayQ 3eUW aI0N ‘AeTdSTp auA OF pTOdDaI 3x9} & 93TIM Jo wioJ eyL ‘“preogqkey ey wory AT[Teteueb ‘ynduT 3xeu 9Yy} speoYy 
NOIDLONNA NOTLONNA 

Ketdstp au} 03 3x98} 383TIM — 24TIM pieoqkey ayy wory ynduT 3xeu ey} UIN}ZeT — pesy 
aHWYN GWYN 


9}TIM/S0 TASp * aTosuoD peay/a0Taap ‘aTosuoo 


TabbHt1L4@S/eo0 aap * 7AOdeurebh 
adXL03eS/e0TAap * 7AOdeureb 
quaagpeay/ao0TAap * Wodaureb 
uado/ao0TAap * y10doeureb 
TeaToO/eo0Taep * AOdaueh 
IebbTALYsv/e0TAep * Wodsoureb 
adkLOYSW/e0TAep ’ AOdoureb 


sua U0D 


(asouenbes peoy ebtuy o3eATid) LYOdad SGNNOd MOGNIM UaMe 
(aouenbes ebtuy ao 7eatid) LSANOAY SNIWLS MOGNIM usMe 
(aouenbes ebtuy o3eaAtid) NOILIGNSY YOSUND Las uose 
(aouenbes peey ebtwy o3eatid) LYOdaY AM TwIOddS use 
(aouenbes ebtuy o3eAtTid) SINHA MWY LaSau auye 
(aouenbes peoy ebtuy o3eatid) LYOdda INGAd LOdNI uare 
(aouenbes ebtuy o}eatid) SINAN MWY LaS ause 
(aouenbss ebtuy ojeatid) LasddoO dOL LYS OLSe 
(aouenbes ebtuy ajeatid) LaSddjo LAST LYS Ose 
(aouenbes ebtuy ojeatid) HLONST SNIT Las Tse 
(aouenbes ebtuy ajeatid) HLONST doWd LAS ddIse 

LYOddu SNIWLS AOIASG usd 

NOILIGNSY DIHdWuD LOaTES UYdS 

aGOW Lasau Wa 

SGOW LES WS 

NMOd TTOWOS dS 

dn TIONDS AS 

(A[Tuo weer3s peoy UT) LYOdduY NOILISOd YOSUND Add 
UALOWYWHO ALATAG Hod 

GNIT ALSTISG 611d 

FNIT LYASNI ‘II 

(auTT JO pus oj ATUC) ANITI NI dSWua ‘Td 

(AeTdstp jo pue 03 ATUO) AWIdSIG NI aSWYa dd 
NOILISOd wosund dnd 

ANIT ONIGHHOdYd YOSHND Idd 

SNI'T LXSN wosund ‘INO 


q1z0de1 

e SIabbh1t1} ‘paepesoxe JT ‘YyoTYyM X UT soUe ISTP e 
— eytedax db 

310da1 

eR STebb11z, ‘pepesoxs JT ‘YyOTYM X UT soOUe ISTP be 
— we 3teax 3db 

(09s/09) s3ztTun yUeTq [TeoOT}ISA UT porNseosuUl 

‘qaoder e siebbt1, ‘/pepesoxe JT ‘YOTYM oUIT e 
— qnoeuty, 7db 

qzodeai e Aebbt1z7 suotj}tTsuez4 

dn uoj4nq JT 38S SAMMNdN dLldD pue ‘’jzIOdeI e Tebbt1}3 

SuOT}TSUeT} UMOp U0}Z}Nq JT ES SATINMOC ALdd 


— soy db 
SjUaUeTS HUTMOTTOF ey} sey 
yotyum /rebbtzpzrodeurey adA} Jo sanjonizys e eed OT Inset 
(TebHT1L rOdsurebh ) Joazts yybueT OT ou} IOJ eTqetzea ajAq oyW JO sseippe suy ezed OT 
aTqtssod st O/I Yyotnb JT Aes WOINO AOI sbeTd OT T 3seaT je ujbuey oT 
YAOOLULNSWY dD pueulioD OT eTqtssod st O/I yotnb JT yes YWOINO AOL sbe[d OT 
aoTaequedo 03 [TRO eyW Aq jJoserd tun OT AdALOMSW ddd pueuloD OT 
aoTaaquedo 07 TTeo ey} Aq jeserd aoTaad OT aoTaequedo 07 [Teo ayy Aq josoard 3tun OT 
aTqtssod jou st O/I yotnb Jt Yes YodATdey uw abessow OT 2oTAequedg 03 [Teo ey Aq yoseird aoTAsd OT 
LSaAnOaY OI eTqtssod jou st O/I yotnb jt yes WogdATdoey uu abessayw OT 


LSanodd OI 


‘-AT@aeTpeuit saynoexe sAemTe pueuwloo STUL 
‘“AT@}eTpouwt soqynoexse sAemTe pueulod STUL 


‘IabbtzLjes Aq jos are SUOTRTpUCD sSOUL ‘onenb peey euy 


03 yoder yodeureb e enanb 0} JUaeTOTJJns ST simodd0 suo Aue *adAL03eS 

3eu -- jUepuedepuT ore ‘SsIeHbbT14 peTTeo ‘SsuoT}Tpuod esoyL snotaeid e Aq jes Uusaeq sey adA} TeTTor}UCO auy, *pejyerdirdjUT 

‘paTJST}#es oq [[TM ysenber pesy butpued e eTOJeq yTuN 320d Ajiedoid aq Kew 310d ay} ye sTeubtTs ay yey os ‘zIOd 

aueb e Aq oul aq Ysnu suUOTRTpUuCD 3eYM SaTTnbuT pueuwlood STUL oueb ay} }e A@TToOTRUOCD Jo adAQA 9yR SaTJTIUSpPT pueUMOD STUL 
NOI LONNA NOI LONNA 

q10dezr yIOdaureb e IOJ suOT}TpuCo aYyA arTNbuT - IJaebbtsrLAsSwW adAj ZaTjTorRuo0s yIodeuebh jueTIMd ayy eAtnbut - aedALOYsw 
GWYN GWYN 


TebHrTLysw/eo Taap * yodoureh adALOASW/20 TAap * 7TOdeureb 


B - 30 


‘pTTeA eq yOU TITM FOIA OI pue 
LINN OL ‘30S eq TTT YoUNT OI ‘/TNnJsseoonsun sem uedo ey4 jI 
SLTNSdY 


TaT[orjuoo yLodeureh yYubTA YRIM pezetToosse yTun- T 
IaTTorquos y1Odeweb AjeT YIM peyeToosse yTun = = Q 
—  4Tun 
SLAdNI 


‘“g0TAap asoTo e Aq paeyojzeu st uedo sty} ssaetun pebundxs oq 
jouuvos soTAep eu, *“peqUeUleTOUT eq [TTTM juUNOD UsedoO soTASepP SUL 


‘PTET] LINA OI eyy pue pTety ADIAKC OI 

ay} :UT PETIT} eq TIT yooTq ysenbeyot ey} UT SPTETFZ 

OML ‘asOTAap e 03 Ssad0e szueITH sUTANOT uado oul 
NOLLONNA 


(9 ‘asenbeyot /3Tun /,,a0TAep’ pOdaureb,, )eoTaequedo 
SISdONAS 


aOTAep 7TOgeuey ayy uaedo 07 Ysenber e - usdo 
AWWN 


usdo/aoTaep * 71Odaurebh 


aTqtssod st O/I yoTnb Jt es MOINS AO! sbeTd OT 

uWaTO CWO pueumioD OT 

aotaaquedo 03 [Teo ey Aq jeserd 4Tun OT 

aotaequedo 03 [Teo ayy Aq yeserd ao0TAeqd OT 

aTqtssod jou st O/I yotnb Jt Wes WogATdey uu abessoyw OT 
LSanoad OI 


‘sqasoenber peer Ajst jes 


0} Butjtem sqzrt0der yrodeweb Aue Taezjgnq 4ndut ey} WoT SeAOURY 
NOILONNA 


Tayjnq yndut zTodoeureb TeeToO - resToO 
SWWN 


Teal D/aotaep ‘ Wodeureb 


31 


OTT} epnypout yrodeureb ayy 
ut sazenbe oy Jed se ‘aedA} TaTTor}uo0o |yy 


butqtirosep eTqetzea a34q eyA JO sseippe eyy e}eq OT 

ml. VL yqbueT oT 

aTqtssod st O/I yotnb FT yes WOINO Aol sbeTyq OT 

AdALOLAS ddd pueunioD OT 

aotaequedo 07 [Teo ayy Aq jeserd 3IuQ OT 

aotaequedo 03 [Teo ayy Aq yesead BOTASd OT 

aTqtssod jou st O/I yotnb JT Jes qy10gATdey wi abessoy OT 
LSanoad OI 


-ATa}eTpouwt saynoexe sAemTe pueulod STUL 


‘pezertaueb ere sztodar ou 3ey Os ‘JjoO peurn} aq osTe ued 

a4r0d au, ‘peqerdzequt ATredoird aq Aeu 310d eyy We sTeubts ayy 

zeu3 os ‘yIOdeureh ayQ ze adTASp Jo edAQ oY} Sjes pueUlOd STUL 
NOT LONNA 


adkj AeTTor}uo0D zrodeureh quezrImod syy yes — eddIOVeS 
GWYN 


adAL07eS/a0TAap * WAodoureb 


TebHt1L3eS/sa0tasep * yTodoaureb ‘adKyD10S/a0TAep’ yrOdoeureb 
OSTW ddS 


-(squdAd 
Tetqzied jou ynq) sqUeAe 3iodeurebh yxeu ey} URTM ysenbeyYoOT ey4 
STITT} pue ysenbeyot ey} UT PTeTF TOTTe ey Ssjzes uoTIOUNFZ STUL 


SLINSAY 
“PTET SOdS AL ey} UT ZUNOD 
aurery oy} se ynq ‘dureqseultz prepuejs e se jou 
uaatTh /yIOder 4seT ey} soUTS SUT} eITEp eu 
durejSoulty, oT 
“sqjtun jUepuedep aoTaep aynjTosqe IO aeaTzeTor 
Zoujyte ut ‘zxodez sty} Toy sontea A pue x 9yy 
k et ‘X OT 
qos are s}tq uo} 4nq pue aATzeTeT ey ATUO 
TeTFTTeEnoO of 
-JJXO onTea oyy Aq pezeotTput st oder 
ON ‘SqzIOdar u0jWNq yWOdeurebh Aue suTejUCO 
pod eT 
qrodoureb 3ybhTI ay} TOF T ‘FFOT SUR ACF O ST 
sseToqns 93T 
ASNOKMWA SSWTOdI St _ 
SSPTD OT 
pouInjzer sjuaas ayy SYUTT 
USAT} XON OT 
:arIe WUaAS YNdUT ZY JO SPTETF 
ayuL ‘SqueAe yNdUT YATA TIT} 0} Pere Aazjnq e eed OT 
-quaao qndut red seqzhiq (AueaqynduTt)josezts ere 
azZay} :SsazAq UT eore eed OT OY} JO eZzTS 3} yybueT OT 
aTqrssod st O/I yotnb Ft ys MOINS AOl sbe[Tq OT 
INSAddWaad ddd pueuwoD OT 
aotaequedo 0} TTeRO ay} Aq qeseird 3tuQ OT 
aoTaaquedo 03 TTeo ey Aq yesead @oTAed OT 
eTqtssod jou st O/I yotnb Jt jes qzIogATdey uu abessoW OT 
LSAnNOgU OI 


‘aTqetteae ATZUeTIMS esoyy YFTA peTystzes eq TTT zsonbe12 

2u. ‘HLONAT OI TIT} ueo se Auew se jou ynq ‘SjzUSAS oUlOS 

are aley} JT 3Nq ‘/peTystTzes eq jou TTTM pueuMoO STYZ “Sj zUEAS 

qrodoureb butpued ou ere aezeyy JI “ysenbeyoT ey jo eore ejep 

au} UT weyy synd pue 7rTOdeureb ey} Wor} sjUSeAS qiodeureb spesy 
NOILONNA 


‘queso ZIodeureb yxeu oy} UINJeT — JUEAgpeoyY 
GWYN 


qUuaAgpReey/a0TAap * VAOdeureb 


32 


j10dez 

e sZebbT13 ‘pepesoxe JT ‘YOTYUM xX UT BsdDUeRSTP eB 
— e3TedK 3db 

310daz 

e siab6T13 ‘/paepesoxe JT ‘YOTYM X UT soDUeRSTP Pe 
— ea tedax 3db 

(oas/og) sqztun yueTq TeoT ISA UT peANseoUl 

‘yr10dei e siabb113 ‘pepesoxe JT ‘YOTYM SUT? e 
— Qnoseuty, 3db6 

qiodei e Aebbt17, suotytTsues 

dn uoj3nq JT 38S SAMIdN dLldD pue ‘nz0dai1 e ATebbt13 

SUOT}TSURI} UMOP UO}#3Nq JT 3S SAMYNMOd ALdd 


— sKoy db 
S]UsUeTe HUTMOTTOJ ey sey 
yotyum /rebbtrLz7odsurey adAj jo aimmyonis e eyeg OT 
(TabbT1zLWodoureh ) Joazts yybueT OT 
aTqtssod st O/I yotnb JT es YOING aor sbeTy OT 
YAOOIULLAS ddd pueumoy OT 
aoTaequedg 07 [Teo ay} Aq jZeso1id qtun OT 
aoTAequedo 0} [TRO eA Aq jeserd BoTAed OT 
aTqtssod jou st O/I yotnb JT jes yrogATdey uu abessay OT 
LSanOau OI 


qUdAqe4TIM/S0TASp* yndut 
41e4S/a0TASp’ yndut 
YSeIy.L}eS/eo0TASp* yndut 


-K[TaVeTpeowuut soeynoexe sAemTe pueullod STUL 


PpoTiad}eS/e0TAep * yndut ‘ TabHTALYSW 
adh WIeS/a0TAaep * yndut U}IM pertnbut aie suoTytTpuoo eseyL ‘ononb peey 3uy 
BHTAILWIES/se0TASp * yndut 0} Woder zIOdeueh e onenb 0} QUeTOTyJNs ST sanooo0 suo Xue 
WOdWzeS/aeo0TAap ’ yndut yeyQ -— juepuedeput ere ‘sTebbT173 peTTeo “suoTyTpuoo esouL 
yesay/s0Taap * yndut ‘petjstzes oq [[TM ysenber peoy 65utpued e e1ojeq Tun 310d 
JaTpuepyuey/ae0TAap * yndut oueb e Aq oul aq ysnuU SUOTJTpUOD }eYM SjesS pueUllodD STUL 
uedo/soTAap * yndut NOLLONNA 
IePaTO/soTAap ‘ yndut 
TaTPueHPpY/e0TAap ’ yndut qroder yrodeurebh e AOJF suOCTRTpUuCD 9sY} 4eS - ZTebbt1L39eS 
GWYN 


s}uUa7}U0D IabHTt1IL}eS/a0Taap * Wodaureb 


33 


eTqtssod st O/I yotnb Jt Res YOINO GOI sbeTJ OT 

YWATO CWO pueulod OT 

asotTaequedo 07 [Teo ayy Aq joseird 3Tun OT 

asoTaaquedo 0} [Teo ey} Aq jeseaad aoTAed OT 

eTqtssod jou st O/I Yyotnb Jt yes yogATdoy uw ebessoyW OT 
LSanddu OI 


*sqsonber peor Ajst jes 
0} Bbutytem sqyr10oder yndut Aue sxtazjnq Ayndut woijy SaeacuUEy 
NOT LONANA 


Jejyjnq yndut reaeTo -— Testo 
GWYN 


IeaTO/eoTtaap * yndut 


"IT TOFS petjstjes ST pueumlod TaeTpuepywey 
® [T}uN aoTAep yndut ayy Aq Adex st ounqjonzys 4dnzzoezUT oul 


SALON 
ssoeippe uoT}OUN}y JeTpueyH ey apod st 
aaoqe peqtiosep Jajutod ejeqieTpuey 2y3 ejed St 
-aamjonizs 4ydnizejuT ue oO} ZaQUTOd e eyed OT 
YaTONVHGGW ANI PpueURIOD OT 
aotasequedo Aq joesead 4tTuQ OT 
aotasequedo Aq joseid BOTASd OT 
qes qIogATdey uu abessop OT 
LSANOFYY OI 
TW OW od 
‘(eqeqzeTpuey ‘sqzueagyndut)zreTpuey = szUueaqyndulMeu 
se 


peTTeo ST uoTjzoOuNJ syL ‘“eoTaep styy Aq pejereueb s}ueae yndut 
aTpuey 0} peTTeO suCTJOUNT Jo YSTT ey} OF UOCTJOUNZ e SppY 
NOLDLONNA 


SOTASp ey} OF Ja Tpuey yndut ue ppe — TeTpueHppy 
aWWN 


JOT PUeCHPPY/20TASp ‘ yndut 


34 


a}eTpouwT WOU ST puUeUMOO STUL 


Sa.LON 
‘ammyoniys Adnizej4UtT oy oF AaqjutTod e eed OT 
UATONVHWaY CNI pueullog OT 
aotaequedgo Aq jyoseiad 3tuQ OT 
aodtTaaquedg Aq jyoserd SOTASq OT 
jes WogATdey uu abessayp OT 
LSANOAY OI 
*suotzounj 
JeaTpurey Jo ASTT ayW OF peppe ATsnotasad uoTjZouNJ e SeAQURY 
NOILONNA 


BOTASp oy} WOT TaTpuey ynduTt ue asaocw!er — JeTpueHuey 
SWYWN 


TaTpuepuPy/e0TAaep * yndut 


_‘pfTea oq ZOU TITM AOIASG OI pur 
LINN OI ‘38S @q TTTM YOUNT OI ‘[nJsseoonsun sem usdo 9y} FI 
SLINSaY 


‘“a0TAaqdesoTD e Aq peyojeul st uedo sty} ssetun pebundxe aq 
jouued SoOTAep ey ‘pe zUeUETOUT eq [TTA jUNOD UedO sdTASpP eyL 


‘PTOETF LINN OI oy pue pTety aAOIAgC OI 

au} «0: UT PETTITT} eq TTT YOoTq ysenboyot eyy UT SpTEeTs 

OML ‘20TAep eB 0} SSaDoDe sqUeIH sUTINOIT UsdO JUL 
NOLLONO 


(9 ‘3saenbeayot /0 /,,e0TAep ’ ynduT,, )aoTAsquedoO 
SISdONAS 


aoTAaep yndut ey uedo 03 Asenbez e - uedo 
AWWN 


uedo/aotaap * yndut 


35 


*KTeatqoedse1 

‘yI0d TaT{Tor}uU0D 3yYyHTA TO WjeT eyA AeyATe wor 
peutezqo aq prTnoys 3ynduT asnoul Qey HutTxeotput 
‘T IO Q TayATeE ST zeUQ 274q be OF JajUTOd be 

T 

atqtssod st O/I yotnb Jt yes YOINO aol 
LYOdWLaS GNI 

aotaequedg 03 [Teo ayy Aq eased 

aotaequedg 03 [Teo ay} Aq yasead 

aTqtssod you st O/I yotnb Jt Jos WodATdey uw 


e3zeq OT 
yzbueT OT 
sbeTa OT 
pueuluoD OT 
tun OT 
aoTaed OT 
abessoyw OT 
LSanodd OL 


* paqoauu0o 


ST asnow ay} YyoTya ze 410d ZIodeureb ey} sjes pueulod STUL 


NOIDLONNA 


yI0d asnou QUaIIMSD |eYyW Wes — Wogwyes 


GWYN 


IOgW}eS/a0TASp * 4yndut 


eaTqtssod st O/I yotnb jt 3s WOINO OI 

Lasau dWo 

aoTaequedg 03 [Teo ayy Aq jose rd 

aoTAsequedo 0} [Teo ayy Aq jJoeseid 

atTqtssod jou st O/I yotnb JT Jos yrogATdoey uw 


B - 36 


sbeTa OT 
pueulliod OT 
3tun OT 
aoTAed OT 
abessay OT 
LSanNOeY OI 


‘a0TAap usdo 3yA OF 
seTpuey butAo01r4sep yNoyATA sotasp preocqhsy ayy Sj}eser Jesey 


NOILONN4A 


gndut ey} Jesel — yoeseyYy 


AWN 


Joesay/aoTaop * yndut 


STITT] epnjtout 3rodeureb ayy 
ut seqzenbe ayy ted se ‘adA} AaeT[Tor}UOCD |yy 


Hutqtiosep etTqetzea a3Aq ayy JO sseippe syy ejeqd OT 

T yybueT OT 

eTqtssod st O/I yotnb JT eS MOINO AO! sbe[d OT 

AdALWLAS ANI pueuMiod OT 

aoTAaquedo 03 [Teo ey} Aq yeserd 4tun OT 

aotaaequedo 07 [Teo ey Aq Aoeserd BoTASq OT 

atqtssod jou st O/I yotnb Jt yes YogATdey uu abessop OT 
LSanoau OI 


‘paqyeidiaqut ATiredoid eq Aew 710d ey} ze sTeubts ayy 
os ‘q20d asnou ay. }e soTAap jo adAj |Yy} SES pueUMOO STUL 
NOTLONONA 


adAj AeTTorAuCD ATOd asnoul JUeTIND 3sYyR eS - adALW39S 
AWN 


adALWI9S/a0TAep * yndut 


310dez 

e sIaebbT1} ‘/pepesoxs JT ‘YyOTYyM XK UT soUe ISTP e 
— e3TedA 3db 

qI10dez 

e SIebb113 ‘/paepesoxe JT /YOTYUM X UT soOUeASTP eB 
— e3Teax 4db 

(oes/o9) s}tTUN yUeTq [TROT PISA UT perTNseouUl 

‘qrodei e szehbt13 /pepesoxe JT ‘YyoOTYyM SUT  e& 
— 4noeurpL 3db 

qaoder e AebbTtzW suotzTsuer4 

dn uo0}3nq JT 3°S SASNdN GLldd pue ‘3IOdez e Tebbtrz4 

SUOT}TSUeI} UMOp—UO}Z3NG JT 3S SATNNMOT dLdd 


— skoy db 
SjusUeTe HuTMOTTOJ ey sey 
yotym /Tebbtzpzrodeurey edAj Jo eanjonizjs e& eed OT 
(TabHbtrzAL7Aodsureb ) Joazts yybueT OT 
eTqtssod st O/I yotnb Jt yes MOINOG AOl sbeTq OT 
YFOOLULLAS ANI pueuuog OT 
aotaaquedo 07 [Teo ey Aq Aaseird yun OT 
aoTaaquedo 07 [Teo ey Aq yoeserad BoTAS OT 
atTqtssod you st O/I yotnb Jt yes YrogATdey uu abessow OT 
LSanoady OI 


“ao0TAep Yodoeureh ayy Aq pesn yey} ST uOTeOTI Toods 

Tebb6tz3 eyL ‘petystyes oq [Tt ysenber pesy Hbutpued e arojeq 

asnou e Aq youl oq YSNUI SUOTRTpUCD 3zeYM Sjos pueUlodD STUL 
NOIDLONNA 


q10dei 310d asnoul e TOJ SUOCTATPUCD eYyW yes — HTILWWeS 
GWYN 


BTIILNQOS/20 TAap * yndut 


B - 37 


spuooesoioTu pToyseizyy 34 OIOTW A} OT 

spuoosas prTouseryy eyy SO9S A} OT 

aTqtssod st O/I yotnb FT yes YOINO AOI sbhe[d OT 
HSSYHLLAS GNI pueunloD OT 

aotTaaquedo 07 TTRO ayy Aq jesoid 4tun OT 

aotaequedo 03 [Teo ey Aq jeseid BOTASG OT 

aTqtssod jou st O/I yotnb JT yes yrogATdoey uw abessow OT 


zsonbereuty e — LSandOad OI 
-K[a,etpouwit saeynoexe sAemye pueumloo STUL 
-(skoey aITYS eyuQ ore ‘/atTduwexe Ioj ‘se) 
peqyotrysea oq Aeu Ady e FO Ajtttqezeeder ayuL_ ‘“yeedezr ued AT 
alojeq UMOp pTeYy eq ysnu Ady e ey} SUIT, SY} SOS pueUMiCD STUL 
NOTLONN4 


prlousery yeedez Aay ayy yes — YseTYyLes 
AWWN 


YS2TYLIOS/20TASp * yndut 


spuooesortotu potied yeader ayy O1OTH AQ OT 

spuooas potied jeedeir 3y} SO28S A} OT 

aTqtssod st O/I yotnb JT jos YOINO dol sbeTq OT 
GOINadLaS GNI PpuUeUBOD OT 

aotaaquedo 03 [Teo euW Aq qesoid 3tuQ OT 

aotaequedo 03 [Teo ayy Aq jeso1d aoTAed OT 

@eTqQtssod jou st O/I yotnb jt jes qiogAjTdey uu oabessop OT 


qsonbeitourZ e — LSanodd OI 

-kTa}etpowuwt saynoexe sAemTe pueulloo STUL 

-sjeader Ay HutjZeedaz e yoTtym ye potired ey} s}es pueullood STUL 
NOT DLONNa 


potied jyeedez Asay ey JES — pottedzes 
GWYN 


potiadj}es/a0Tasep* yndut 


38 


‘-pofoi4sep ere (s)jUeAe YnduTt ayy jo sjuaqUOCD aUL 


SaLON 
peirtsep se 
durezSoult.L oT 
K eT ‘X eT 
TOTFTTENO OT 
Spod eT 
sseToqns eT 
SSPTID OT 
*ZUSATPXON ST OTOZ & SEY 
quaAd 4SseT ayy /1eYZEbOR sjuaAD |YyW SYAUTT 
qQUSAq}XON OT 
:9I1e WUeAD YNdUT ayQ JO SPTETJ 
auUL °(s)sqzUaAdD YNdUT YATM eere Asjjnq e eyed OT 
-juaaa yndut ted sajhq (JueagjnduT)joezts ere 
aia, :seqAq UT eore ejeg OT SYR JO ezTs 3yA yybueT oT atTqtssod st O/I yotnb JT jes WOINO Aol sbheTd OT 
atTqtssod st O/I yotnb JT 4s YWOINS AO! sbelTa OT LUvLs CWO puewllod OT 
INAASALIUM GNI PpUeUROD OT aoTaequedo 03 [Teo ayy Aq jeserd ytun OT 
aoTaeqduedo 0} [Teo ayy Aq jYoserd 4tuQ OT aotaequedo 03 [Teo ayy Aq qesoid aoTAed OT 
aoTAaequedo 0} [Teo ey Aq joserd BOTAN OT atTqtssod jou st O/I yotnb JT jes q10gh{deu uu obessoyW OT 
aTqtssod jou st O/I yotnb jt yes WodATdey uw abessoy OT LSanodd OI 
LSANOdY OI 
‘pueumioo dojs e reqye 4tuN ey} s}PIeRSeT W7RPIS 
NOLLONNA NOTLONN4 
sioTpuey [Te 03 (s)juUeAS YnduTt ejzebedord — YUeAge TIM dojs toxye yreySer — 47e4S 
AWWN GWYN 


qUaA ge TIM/SoTAap * yndut 371e4S/a0TAap * yndut 


B - 39 


"JE AOJ petFst}es st pueuMiod Ta[pueHjesowey 
e [Tun soTAep preoqhaey oy Aq Aday st aerNjonzAs AdnirSeRUT eUL 


SALON 
sseippe uoTjoOUNy TeTpuey suy @apod ST 
@aaoqe peqtiosep Tajutod ejeqieTpuey ey eed ST 
-aimjoni7s 4Ydnzzi9ejUuT ue oF} AaqUTOd e eyzeq OT 
USTONVHLaSaudaW aay pueullloD OT 
aotaequedo Aq joseird qtuq OT 
aotaequedo Aq jaserd BoTAed OT 
Res WZIOgATdeYy UW abessoay OT 
LSANOGUY OL 
TW 
‘ (eqeqreTpuey ) aT puey 


:qjeser prey e arojeq 
dn ueaTo 03 peT[Teo suotjoUNJ Jo ASTT 2Yyy OF UOT JOUNJ e SppY 
NOLLONNA 


SOTAep sy} OF} TaeTpuey joeser e ppe - JaTpueHjeseyppy 
GWYN 


JeTpuepjyeseyppw/sotasep- preogqksy 


SUOGISeTPUueHeSaY/20TASPp * 
Joesay/a0Taoep* 
IaTpueHzesayUpy/so0TAap * 
XTIZEWPeSY/SOTASPp ° 
qUdSAgpeay/soTASp~ 
IPITO/a20Taap* 

‘preoqhkay 


JaTpPueHeSeYppW/e0TASp 


preoqiksyx 
pireoqheyx 
pieoqhsy 
pireoqhey 
preoqkey 
preoqghey 


sjua3U0D 


B - 40 


*(squaaa 
Tetqzied you Anq) sqjuease preoqhey }xeu ey YITM Ysenbayo!I ey3 
STITJ pue ysenbeyYyoI ey uT pTeTy AOTTS ayy sjos UOT OUNT STUL 


SZLINSdAY 
O18Z O} JES pue ‘/pesn jou sre 
dureysoutL et ‘A eT ’X eT ‘sseToqns eT 
qos are sjtq ped oTZeumu pue 4jtus eyy ATUO 
TSTFTTeENO oF 
sqyiodeit umop/dn Ady 3xXeu sy suTe UCD 
@pop eT 
AGIMWY SSWIOGI St = 
SSPTD oT 
pouinjzer sjueAe oy SYUTT 
USATPXON OT 
soe QUdAdD YNduT ayuW Jo spTEeT; 
euUL “SzUeAD YnduT YIM TTT} 03 RPeTe Aajjnq e eqed OT 
‘qusao 4ndut Jed saqzAq (3UaAqyNdUT)jJoezTs ore 
arey, :saqdq UT eae eed OCT ZY} JO OZTS ayy yybueT OT 
eTqQtssod st O/I yotnb Jt 3esS YOINO Aol sbe[aq OT 
LNAASGWaY addy pueuallod OT 
aoTaequedo 03 [Teo eyyW Aq jesard aoTaeq OT 
aTqtssod jou st O/I yotnb Jt yes WZIOgATdaey uw abessay OT 
LSGNOdY OL 


‘aTqetTteae ATjUeTIMD |ssoyy YIM peTjstzes oq [T[T ysenberz 

ou ‘HLONAT OL [T[Tt} ueo se Auew se you ynq ‘sqUaAa oUOS 

ole si3auy JI ‘petystjes oq OU T[[TM pueuUMlod sTuy ‘SjUSAD 

pieoqhey butpued ou are atsy} JI ‘ysenbayot ey jo eaie ejep 

eu} UT wWeyy ynd pue pxreoghsy 9y3 WoOTJ SjUaAd preOCqhsy mMeT peosy 
NOTLONNA 


"Quaad preogqhkey 2xeu ay UINeT — JUSsAgpesY 
aWYN 


quaagpesay/aoTaap* preoqheay 


etTqtssod st O/I yotnb FT yes YWOINO AO! sbeTq OT 

YWATO AWNO pueuRlod OT 

aoTAequedo 03 [Teo ayy Aq yYoserd @oTAaqd OT 

atTqtssod jou st O/I yotnb Jt yes WogATdoy uu abessoy OT 
LSanNOdY OF 


‘sqsoenbez peer Ajstjes 
0} ButjtTem suotztsuer3 say Aue Aayjnq ynduT oy} worj seaciPy 
NOILONNA 


Zajjnq yndut preoqhkey reaToO — TePeTO 
GWYN 


IeaTo/eotaap* preoqhkayx 


4] 


‘om yoni4s YdnizajuTtT TaTpuey eyj oO} Jajutod e 
UPIGNVHLASAUWaY day 
aotaequedo Aq joseid 
aotaequedo Aq joeseid 

jes yoghTdey uu 


eyed OT 
pueuloD OT 
qtun OT 
BOTASd OT 
abessow OT 
LSaNOdd OL 


“suoT}zoUnj 


ZaTpuey JO 4STT ey 0} peppe ATsnotaerzd uoTJouNJ e SeAOURY 


NOIDONN 


QOTASp oy} WOIJ TeTpuey eset e eaoURI — Ta TpueHjosewPy 


SWWN 


JaTpuepy esayuey/soTaap * prveoghay 


"xTiqzeu ASY QueTAMND ay OF xTI}eU 
Sjes pue ysenbeyol ey} UT PTET} AOITS sy Sjes UOTIOUNJ STULL 


SLINSAY 
‘xTI}eu sty Jo (g AIC U) 
oy4q ut (g GOW U) 4Tq 3e ST U apooksy 
Ioj Key ayy Jo a3eqs ayQ :aqzeqs SkdY YOoORd 
qoeTjer s3zTq ZUeUOCdWOD ssoUuM sazAq Jo Aerzre ue 
>XxTIZeu Ady SUF UQIM TIT} OF} Pare Asjjnq e eyed OT 
*xTrqzeu Aay sy} PToy oF Yybnous bHtq eq ysnu 
SsTuj :soqAq UT eare eRe OT dUW JO aZTS dy yqbueT oT 
eTqtssod st O/I yotnb Jt yes YOINO dol sbeTq OT 
XIULWWdWaY day pueuloD OT 
aoTAequedg 03 [Teo ay Aq joseid BOTAed OT 
eTqtssod jou Sst O/I yotnb jt jes yWogATdey uw abessoyW OT 
LSANOAY OI 


*xTazjzeu Ady 
ey} ut Aaey ATaao Jo a3e4Ss uMOp/dn ay spear uoTAOUNJ STUL 
NOI LON ef 


xTiqzeu Aay pxreoqkey YueTIMD ayy peer — xtTr}eWpesy 
GWYN 


XTIZeEWPeSY/20TASp* preoqhkayx 


42 


‘ganjoni3s ydnizejuT JeTpuey ey} 03 TaquTod e ezeq OT 
ANOCUSTONVHLASAY day pueuloD OT 
aotaequedg Aq jyoserd 4tuQ OT 
aotaequedg Aq joserd BoTASad OT 

yes qrogATdey uu abessow OT 
LSanOad OI 

* pa zeTduico 

sey TaTpuey ay} UATM paezetoosse dn—-ues[o jeser yey} SozeoTpul 
NOILONNA 


amooo ued jeSsaT 2eYU SeOTpUT — sUOgTEeTpUeH}esSey 
HNN 


QUOGIaTpueyHyesey/eo Taap * p1eoqhoey 


eTqtssod st O/I yotnb Jt Yes WOINO Aol sbeTd OT 

Lassa dNo pueumlog OT 

aotaequado 03 [Teo ayy Aq jyoeserd BoTAed OT 

aTqrssod jou st O/I yotnb Jt yes y1ogATdey UW abessopy OT 
LSanogd OI 


‘aoTAep uedo 3} OF 
so[Tpuey HutAor3Ssep yNoyWTA sotaep preoqhsey oy} S}eseT Josey 
NOTLONNA 


pieoqkey ey} yaser — zoesoaY 
AWWN 


Jasay/aoTaap ‘ preoqkeay 


43 


OSTW dds 


GHLNOdY YNAOI 07 32S GUYOI JO pTEety ros OT 


ananb ayy ut eq Aew ysoenber syL 


" yroqe 


*ysonber 


3sonbelz OI 


SLTNSAY 


0} ysenber Jo Uo! 
SLAGNI 


“aatqoe ATRUeTAMD 10 


OI yooods e s7T0QY 
NOLLONNA 


(3sonbeyo!l ) o1W0qu 
SISdONAS 


ue yIoqe — O1}10qv 
aWWN 


OI HMoqy/saoTAap * 10ze1TeU 


9} TIM/90 TAap ‘107 e1TTeU 
do3S/71e4S/a0TAap 107 eTTeU 
qasay/ao0Taap ‘10; e1TTeU 
peay/aeoTaap '10R,e1TTeU 

aod TAaquedO/a0 TASap * 10OZeITeU 
YSNTJ/aoTaep ‘10, e1TeU 
BOTASGESOTD/a0TAap * 10, e1TTeU 
OI Woqy/s0TAap ’ 107 er71TeU 


$}uajuU0D 


44 


OSTW dds 
SLINSaY 


HSN14 GND — pueulllop OT 
SLANI 


-sqasonbei yooaeds penenb pue ssaiboid-uTt [[Te szoqy 
NOILONNA 


‘()oIpues/()OICd 88S ‘*pueUMIOD sdOTAep prepue AS 
SISdONAS 


sq3sonber penenb pue ssezboid-ut [Te Woge —- ysn{Tq 
AWN 


YSNTJ/aoTaep ‘10}e17TeU 


OSTW ddS 


“PeIePTTRAUT SIequTOd soTASep pue yTuN YIM YAooTd ysonbeyo!l 


SLTINSAY 


yooTq ysenbeyo! 
SLAdNI 


"31q ebundxse ayy sj}es adTASdeSOTO ‘aS JOU ST 3Tq abundxe 

pekeTeap ay} pue o1az 0} saob jYuNoD usdo ay} JI ‘pebundxe 

ST aoTAdp ay} ‘eS ST 4Tq abundxe ay} pure Q 03 Ssaeoh 

yunoos ay} JI “UNOS Usedo ay} SeoNpeT OSTe sdTASdeSOTO 

‘aoTaequedo Zeyjoue TT}uN OL juaenbesqns butjueseid ‘quo! 

au} UT SPTeTJ AOIASG OI pue LINN OI ey sezepTTeaAUT SsoTo 
NOTLONNA 


(3senbsyO!I )eoTASdesOTO 
SISdONAS 


soTASp TOZe7TTeU SY} OF ssao0o0e o7eUTULIS  — BOTAVdESOTO 
aWWN 


BO TASMeaSOTO/a0TaAap ‘ 10zerT1TeU 


45 


“pueullod 34TIM 
OS'TVY ddS 


(ATuo osn [eur AUT) 
sedeus yINou JO WIoJy pesserduioo — odeys 
SJoZoUTT [Tu ut FYyYHTey YyANow — JYybTeEYy 
(but[eos TOF suOop uUOcTSTATP) 
L9°¢€/SiSUTTT TW UT YFPTAM YZnou — YPTA 
*Jes SpTeT} duyol 
SLTASAY 


- qybTtoy 
- UFPTIM 
bs IOIAG OT 
away GWO — pueuloD OT 
3Zsonbei pest TOF WIOd shessou -— abessow OT 

:IOJ Ydooexse ysonbezr o4TAM poezZeloosse 

ey} worijy petdoo aaznqjoniz4s qi 107ZeATeU |Yy YT GUOoI 

SLNdNI 


oo Oo 


‘Sen,Tea peurmnyerz ATsnotasid wory WUueTeJJTtp eq you 

Aeu soedeys Yyjnouwl sy} eased Sty} UT Fey SION ‘Speer 

ezow Aue ensst jou pTNoys su/s ey pue psYsTUT}F 

sey ySsenber 33TIM oy} zeY SMOUY TJesn 3yR MOY 

osTe ST STUL ‘ATOITa ue YATM Jasn ayy OF pouIN jez 

oq [TTTH peer ayuq /ysoenbezr peer ayq se Tequmu 4tun 

—opnesd ours 3y} YT onoenb yndut sdTasp ayy UT IO 

sseiboid UT o3T1IM OU ST aTey} JI ‘“SeTT} Ty’ SYR VES 

"quyOI peer oy} OF pTEeTF qr ojerTTeu ay} OFUT UO! 

Jozerreu oyy HhutAdoo Aq opeu ATtsee st uoT}etToosse 

Sty} ‘duOI (a3T1IM) TOReATeU e ST GYOI YRNOoU-peselt syy 

UT a1N}ONAAS ASATJ SYR BOUTS “TTeoO adTAeqUedO 3YR 

&q peubtsse requmu 3tun—opnesd sy Aq ysoenber 33TIM 

e UTM poeJetToosse st Ysenber pear yoereq ~~ (pebueyo 

sey buTyzeulos ueyam ATUO suUOpP oq OF but jepdn HutmoTtTe) 

edeys peuinjzez ATsnotaeid ay} wWory AUeTeJJIp oq OF 

posquezenb st peur jer odeys oyL ‘resn ayy OF soedeys 

yQNou SUINJeT soTASp TOReATeU su JO pueUMIOD pedl dU 
NOLLONNA 


“OIpuss/OICd xeS ‘“puReUMIOD SsOTASp pTepue Ss 
SISdONAS 


@YTIM pe}etoosse 
ue WoL} odeus YNoUu jUeTeJJIp }xeu eyy uINJoeT - peay 
4WWN 


peosy/aoTasep *r07erTTeU 


OSTW dds 
GYOI JO p[Tetj AOIIW oT se owes —- TOMA 


(xew) $9 — osoUMTOA 
oo¢ze — bezjdures 
JJO — syyNow 


OTeW — xoS 
TeinyzeNn - Spoul 
ZH OTT — Yo atd 
SNUTW/SPIOM OGT — a3e1 
-39S SPTSTF AYO! 
SLINSAY 
poesn jou — sbeT] 


(pazTTeT}IUT eq YOU pseu) qyOI S,tesn ey} -  ysenbexo! 
0 eq ASnwW — TEequMN zTUN 
,eotTAep AOReTTeU,, eq YSnu — sUeNSOTASpP 

SLNANI 


‘31q ebundxe pekeTep ey} sieeTo pue quo! 
au} UT JaqQuTOd apou aoTAap ey} Se104S sdTASqUedO ‘AT[Teuld 
‘STTeJep eTOUl OJ pueuUlod peat ay} ses ‘“sjsenbeT ajTim pue 
peei butztuoryouds ut esn OJ quOI ey} OF Jequmu 4TUN—-Opnesd 
e subtsse uay} eotasquadQ ‘“euop st usedo ey} Jaqje jes aq 
4snul santTea ayy ‘sumed asay. OJ sonTea }[Nejep-uou asn oF 
USTM SZIaSsN JT 3#eYQ SION ‘“GYOI OY JO SpTEeTJ ezeTAidoidde syy 
UT Z@S are syynou pue ‘Aouenbezjy but{Tdues ‘epou yoqutd ‘yo ytd 
‘aqe1l /xaS IOJ senTea W[TNejJed ‘“(aNOI) YOoOTA ysenbeyYoI s,azesn 
au} SOZTTRTRTUT (eUO YsITJ ayy ysSNL You ‘suedo [Te ACJ auop) 
aoTaequedo /}XeN ~*“(Sepoo UINjeT TOIT eTqtssod Io} saTtJ 
T°’ pue y° oy oes) peurnjet st Torza ue ‘TTeFJ suotjeiedo asauy jo 
Tayjyte JI “sreygnq oTzeWs S,ATeaATIp sey} azeOOTTe pue soTASp 
otpne ayy uado 03 Aduez }e TTT eoTaequedo ‘pouedo useq sey 
JOATIP ayy suUT} YSITF SYR ST STU JI °(4Ig9TUN GN) Tore ue 
suinjei /orez—uou JT pue ‘Zequmu 3tuN ayy SYoeYyo eoTAequedo 
‘QoTASp TOPeITeU ay} OF sseooe squeIb suTANOT soTaaequedo SUL 
NOIZONN el 


'(g ‘3senbeyYyol ‘0 /,e0TAep’1OZeIIeU,, )eTAequedOo = ATOIIE 
SISdONAS 


SoTAep 1ozeTTeu |yR uaedo — soTaaequedo 
AWWN 


uadO/adTAap ‘107 e71eU 


c 
a 
~O 


OSTW dds 
SLINSAY 


LYWLS GWO TO dOLS GWO = pueuMioD OT 
SLOAdGNI 


*“3zIe}s 03 AYsoenbexr penenb smoT Te pue 
(Aue JT) yoosds satjoe ATAUeTZNS 9syA syIeRseT 4IeIS 


“butzre,s wory sysenber penenb Aue sjueasid 
pue (Aue JT) yooeds aatqoe ATAuerTImMS |9uyA syztTey doqws 
NOIDLONNA 


*()OIpues/()OICd aeS ‘“SpueUMICD asdTASp prepueqs 
SISdONAS 


dojs Taqzje asotTaep oy} sypIeSerT — yes 
SoTASp oy sdoqzs — dos 
WYN 


dojs/q1e4sS/aotaap ‘107 e11euU 


OSTW dds 
SLTNSAY 


LaSauY CWO = pueumloD oT 
SLANI 


‘peddojs useq sey 4I JT sotTaap sqzrTeqsoy 


‘penenbua Io aaTqzoe ere Ady} TeyZoEyM sysenbel ojTim/peser [[Te sPIoqy 


‘pezTTetT#tTuT eq qysnf sey 4T ybnoy} se aoTaaep ey} SszeseY 
NOILONNA 


‘()OIpues/()OICd eeS ‘pUueUMIOD sdTAep prepueSs 
SISdONAS 


aes UMOUY eB OF SOTAeP ey JoeSeT -— Jesoy 
HWYN 


Josay/ao0Tasp ’ LoJVeTTeU 


47 


SUTIM/20TASp * 
*TeTTe1zed 


dojs/ao0Taep 


q71e4S/ea0TASp 
*TaTTe1zed 


sweiedgjzes/aoTaep 


qoaesay/ao0Taap’ 
pesy/so0Taap ° 
ArIanO/soTasp* 
*TeTTe1red 


20 TAaquedO/a0TASp 


USNTA/2OTASP * 
BOTABG2SOTO/20TASp* 
*TeTTe1red 


ITea[D/aoTAsp 


OLUTbeg/a0T Aap * 
OI Hoqy/a0TAap * 


[eT Te1zed 
[eT Te1zed 
TeTTe1zed 
TeTTerzed 
Te TTezed 


TeTTezed 
TeTTe1zed 


Te TTe1ed 
TeTTe1zed 


$quUajUuOD 


“UOTReAQUSUMDOP VsoOTASP OTPHY 


“puewUods proy 
OSTW ddS 


*"perinoso AOIZe sy} eTeyM Hutaz,s yndut sy y 

UT UOT}TSOd aYyA ST Ten}oW OT /(ATqGUOUd GN) 1OIZAe aueuoYUd e 
Sa}eoTpuT epood uIN}eT 9uj JI ‘pessaooid ATTenqoe sem 7euR 
Hutr3s yndut ey Jo yRhuET ey} OF Jos ST pTeETJ Tenqow OT 
SUL ‘“AYOI 24} JO PTEeTJ TOG OT syW Ses UOTJOUNJ SUL 


butz4s yndut Fo yyQbueT — 

butaz3s yndut - 

aLIYM CWO — 

q3i0d abessou 

ovTeuloy Jt 

oTeu FT 

epow oTzoqor FT 

@poul Tem eu jT 

apou yo3utd 

youtd 

a}e1 butyeeds 

peer aq OF OTe SYyyNOU jI [ 

poeitsep ore syQnou ou jt oO 

SYSeU UOT}OSTeS TeuueYyo OTpne Jo Aequmu 
(pTety styz Jo uotTydTrzosep 

IOJ uoT}eAUSUMDOP SOTASp OTpNe sas) 
SYSeU UOCT}OeTesS TouueYyo OTpne jo Aerize 


On Oe ! 


SLTNSAY 


yybuey OT 

eyed OT 
pueulog OT 
abessoaW OT 


_ xo9S 


Z @poul 
2 yo utd 
es ae 


su nou 
— syseul wu 


— syseul yo 
dyOI AO7FePATEN 
SLAdNI 


‘T 03 Jes 


aq ysnu Jajourered syynou ay} ‘spear butop aq o 4 
Hbutob aie noA Jt 3ey 2}ON “Tasn ayy OF adeys 
yqQnoul TeTRITUT ue UMNO pue FT SAOURT T[TM 33TIM 
‘onenb 4ndut sdTAep 3xy} UO 4ysenbseT pear po }etoosse 
ue ST ar0Uu} JI ‘“Asenber yooeds ayy suzojsed 


NOTLONN ed 


*()oIpuaes/()OICOd 38eS ‘pueUMIOD sOTAaP prepUue AS 


SISdONAS 


SOTASp ToOJeTTeu ayy 07 Ysenber yoosds pues ~ 33TIM 


WYN 


94 1TIM/S80 TAaep ‘107; eT1eU 


48 


‘pswATdey ayy [Tzun peyroder eq 3,U0M SsiTOIIE O/I 3SOW 
‘OoJezZ-UOU aq T[TM TOIIG ayy ‘/peTTey OTuTbeg ey} JI 
-[[Nu aq [TTA Torq ‘/papsesoons OTUTbeg ey} JT —- ato1q4g 
SLTINSdAY 


-uado 3e SOTAad OT ORUT Ynd pue ‘4TUT 
3e ATINg apou ,d0TAep’ TeTTezed,, eyz oO} TequTod ——- eponsoTtaep 
‘SZajowered peitnbezr TayjO s,uoTZOUN; sy} se [Tem se 
‘ssa00id 0} pueuUMIod OT UT UOTROUNJ pTTeRA e HuTuTejUOo 
‘(uoTITUTjap/ezts IOJ T*TeTTered ses) BZTSIPdqyxXY OT 
@ZTIS JO yOoTE ysenbey O/I ue oF dajutod ——  ysenbeyot 
SLAdNI 


*butnenb 


OdId PTA peTpurey ere sysenber aTdT3#INW “MOINS OI se Teaou 
‘Xtsnouoiryoudse powrojied st ysenber a4TIm TO peer pTTea yY “euTynot 
HswkTdow prepuejs ey} eTA peTeubts st uoT ze Tduo| ‘peqetduco jou 
‘unbeq se TaTTeo ayy oO} uINAeT snyQ pue ‘/olUTbeq Aq pozeTFTUT Ajerzeu 
aie SO}TIM pue spesy “MOINS OI se peuwtojied oq ued UOT OUNF 9yy 
‘pajoajtes os JI ~*(sat}Tnutj}ucostp pejetoosse s}T IO) OTbOT 
HutTpuey ydnizequt Aue uo puedep jou op pue ATsnouozyouds 
peutojied aze suotjounjy ey} /384TIM XO pest ueYy} TISYAO “SsoTASp 
TeTTezed ayy 0} apeu ysoenber O/I e sazeTATUT uoT}OUNF STUL 
NOITDLONN4 


sseooid O/I ue dn zreqs —— oUTbog 
aNWN 


OlUTbad/so0TAap’ TeT tered 


‘O19Z oq TITM Zo11q ayy ‘/peTTey Woqy ey} JI * (jes 
sbeTa OT JO G 31q) pe yogqe se pebbeTy eq [TM ysenber eyy pue (zZ-) 


GALNOdY YNSOL¥# Sq TTTM ToIIq ‘pepsadons yLOqy eyy JT -—- IOI 
SLTNSdY 


‘peqrogqe aq 03 ST }#eyy YooTa AsbyoI ey oF ATezutTod —— qsonbayot 
SLAdNI 


-poaousr ATssatuted st 31t ‘penenb 

ST 3senber eyi JI ‘“ATezetpoumt peddojs st 4T ‘aaTzoOe ST ysonber 

au. JI ‘ySenber a4TiM TO peer peTjtoeds eyy syroqe uot youn STUL 
NOLLONNa 


qysonber O/I petytoeds ayy yroqe —- OI}toqv 
aWWN 


OI Mogqy/eoTaap’ TeTTezed 


B - 49 


uedo/a0Taap* TeTTeared 
OSTW das 


uadg Aq jes ‘apou aoTaAap oy} OF AejUTOd - epoNsdTASep 
SLAdNI 


‘agoTaap TeTTeied ey} 0} ssadoe aTeMzjos saso[o uoTIoOUNF sSTUL 
NOILONNA 


(SPONSOTASP ) BO TASdeSOTD 
SISdONAS 


y10d TaTTe1ed ayy asoTO -—— esOoTD 
GWYN 


DSOTD/20TASp’ TeTTe1red 


auou —— 10119 
STINSAY 
YVATO GWO pueulllioD OT 
aotaequedo Aq es 4tun OT 
aotaaquedg Aq jes @oTAed OT 
pezZzTTeTytTut yIOgATdey uu abessopy OT 
LSANOAY OI 


-(reaTO 0} Jayyngq ou) s,SLy ysn{ uot QouNJ sTUL 
NOILONNA 


Iajyjnq wrod TeTTered ayy aeeTo —- TeeToO 
aANWN 


IP9TD/aotTaAap’ TeTTered 


B - 50 


-OTaZ—-UOU aq [TTTM TOIIG ey} UEeYy} ‘peTTey uedo ayy JI 


-T[Nu eq [ITM ToIIgG ‘pepsesdons uedoO ey} JT —- 10TIG 
apou soTAep ey} OF AaqutTod —- od 
SLTASAY 
porzoubt — sbetj 
iii @eZTISredq}zxXy OT azts Jo aq (ii) LSAW YOoT yYsenbayot ji i INWLYOdNI 


(aaoqe NOILONAA ees) sbheTared OT Jo esn ALON 

"euTqnor uedo ayq Aq 

PeZTTeTFIUT aq 03 (uOTATUTJep/eztTs IOJ T° TeTTe1red ses) 
SZTSILGIXA OT OZTIS JO YOOTG ysenboeyoT ue oF Ja yutod — Asoenbayot 


pezoubt — 3tun 
,2OTASP’ TaeTTezed, Hutrys TelSTT OF Tequtod - ouweured 
SLNAdNI ‘olaz—uoU oq [[TTM TOTTG ey} ‘peTTesy YysnTA oyy FI 
‘T[Nu aq [ITM 1OIIg ‘pepesoons ysnTA eYyz FT -- 4047g 
-41un/aotaep TeTTezed suo ATuUO ST eTey} osnedeq SLINSAY 
‘9 03 SPTeTF TUN OCT pue dOTAEq OT SY SEZT{TeTRIUT soTasquedo 
HSN14 CWO pueUMOD OT 
‘QoTASp ayy SeSOTO TeuMO ey [TQUN eotaequedg Aq jes 4tun of 
peMOTTe ST sseooe Tay}O OU pue pejUeIb ST asn aATSNTOXe “jes aotaequedg Aq jes aoTAed OT 
St (she[Tqied OT JO G 4Tq) Tq SseDDe-poereys eyz sseTun “sdTAep paeztTetqztur yzogATdey uu abessay OT 
TeTTered ay} 0} sseooe aTeM}jJOS Toysenber oy} SMOTTe uoTIoOUNT STUL LSANOGU OI 
NOILONNA 
‘aoTAep [eT Te1sed 
(sbeTy ‘qsenbeyot ‘ytun ‘ouweured)aotasquedo ayy Toy senenb YsenbeT a3T1IM pue peer 3A sobind uotjoun} STtuL 
SISdONAS NOTLONNA 
3z0d [TaTTered ey} uedo 07 ysanbezr e —— uado 410d [TaTTered ay} 10¥ sysenber C/I penenb TTe Testo -- ysnTd 
aWWN aWWN 


uedO/asotaap’ TaTTezed ysn{d/aoTaap’ TeTTered 


ol 


sueled}es/eotaep’ TeTTeied ‘olutbeg/aotaap: Tet Te1red 


OSTW dds 
"OTEezZ-UOU 9Oq [[TM TOIIG syy ‘poeTtey peoy ey jI 

"T[TNu eq [T[T4 TOIIG ‘paposaoons peay oy} JT -- TOIT 
SLTINSAY 

-eqVep oy 3nd 03 sZeYyM TaqUTOd eed OT 

UT peer JOM [TT}#UN SATAOSeT T[- 0} 

yes JT TO ‘/aATadeT O03 STaRZORTeYO Jo Tequmu yybueT OT 

peitsep pue aetTqtssod O/I yotnb JT YOINO AOI sbheTq OT 

away dWo pueuoD OT 

aotaequedo Aq jas 4tun OT 

aoTaequedg Aq jes BOTASq OT 

peztTetqtut yro0gATdey uw obessow OT 
LSandodd OI 


‘pebpetmouyoe jou st (jsaenber eyeyspuey *-a°T) ynduTt butpued ‘opew 

useq sey ysenbez peer ou JI °(00xO ATJUeTAIND) pear st Jog ue 

[Tqjun peer st yndut aseo yoTym UT ‘pesn ST [T-— ssatun ‘YyybueT OT 

UT paTjtToeds st siajoezreyo Jo Jequmu ey, ‘1e4stTber O/I TeTTered 

au} WOTT pee aq OF SiJa}OeTeYUO JO wWeatjs e sasned UOTIOUNJ STUL 
NOITZDONNA 


yiod [eTTered worj yndut pear — peoy 
AWWN 


peay/eoTaep’ TeTT ered 


pearasol L-¥ 
T=99 TIM‘ 0=peort = € 
a[bbo3 Asnq ut raejutad MOT Z 
4no xzeded MOT T 
peyoeTes rajutTid MOT 0 
NOILONNAI dAILOW JLId Sn}e4s OT 
SLTNSAY 
(yo) AUYNO dWodd pueuoD OT 
sotaequedo Aq jes 4tug OT 
aotaequedo Aq 3esS BoOTAeq OT 
peztrTetytut yrogATdey uu abessaw OT 
LSANOFY OI 
‘SsTaqystboer 
pue seut,T wod TeTtTered ayy jo snzeqs ay} UIN}QeT UOTIOUNF STYL 
NOILONNaA 


snjejs out[/p_Iod TeTtTezed Azenb —— Arend 
AWWN 


Kianod/aeotaep* TeTTezed 


O2 


‘O1NZ—UOU Oq TTTIM TOIIG ey} ‘peTTejy sueregqes oyy jI 
‘[T[nu eq [[tT AOIIG ‘papesoons swereg}es ay} JT -- AOA 
SLTINSdAY 


“Fos ST 4TQC ACOWAOY 

ayy Jt ATUO adTAaquedO UO PeTIT} ST PTETJF STUL 

( COLOEOEOEOPOATIGX °“6H°9) “Jos ST sheTjxred oT 

JO 341Tq AGOWAON Jt ATUO pesn are SiOZJPeUTUTAL, 

‘ONTeA PTTeA 3SsemoT/m AerTe ANNO TT[TJ ‘paesn 

sieyo g uey} SSET JI “siaqoereyoO uoT}euTWIAR 
jo Aer1e a3Aq-g poetsepi0c_bhutTpuscosap IIDSW AezAWWIaILd OT 


“SATIOLUT 
AerTeurse} ‘sseooe aatTsnjToOxe spTetA 0OX :ALON 
U’TeTTezed iO T’TaeTTerzed ut uoTATUTJap ses sbe[Tqied OT 
(O1eZ OF 28S 32q LSAW) T°TA UT pesn jou sbeTd3Xad OT 
*uOTReINHT JUOO 


qUuaTINO $,e0TAep TeTTered ay} yoeTyJer oF 
uedo Aq peT{T} ete spTeTy HUTMOTTOJ ay + aLON 


(60) SWWUWdLas dWodd pueuloD OT 
aoTaaquedo Aq jes 3TuUn OT 
adTAequedg Aq jes BOTASd OT 

peztTet4tut yrogATdey uw abessow OT 
LSaAnodd OI 
(iiii) “NOILLONNA SWWYWdLaS AHL AT AINO GHONWHO 4d NWO SuaLaW 


-WUWd UAHLO TIw “ATUO sT[eo soTasquedo 07 suTeyYIed sheT qos OT 

JO 3Tq pereYUsS eyuL ‘sueredjas OF [Teo e ANOYWTIM JoeseT/jes 

eq ued sbeTqies OT Jo 41q SpowjoyY syL “penenb 1oO aaTjoe o1e 

Ssoqtim 10 spear Aue JT sebueyo MOTTeSTp TTT }I *“Wod [TaTTered 

au} AOJ sIejoweized shueyo OF TaTTeo ay} SmMOTTe UOTIOUNJ STUL 
NOILONN4 


3ZIod TeTTeied ay} 10jJ siTajoureted abueyo -- sureiredzas 
aWWN 


sueiegj}as/aotaep’ TeTTered 


‘OJezZ-—UOU eq T[TM JOIIG eu ‘peTTe}y jJesey oy} jI 


‘T[nNu eq [ITM ToIIg ‘pepesoons josey ey} JT -- Tory 
SLTNSAY 

Lasau dWo pueullliod OT 

aotaequedo Aq jes 4tug OT 

aotaequedo Aq jes BoTAeqd OT 

peztTerytut yogATdey wi abessoyW OT 
LSanodd OL 


“SeNnTeaA AZ[Nejop 
our} dn—j0oq ATeYy} OF Siojouered pue sbheT} s,Wod sy} sjes 
pue juezmos pue penenb yOG sqysonber O/I [Te SsWoqe RI *“uoTRTpuoS 
peztrtetqytut ATysery szTt OF qi0d [TeTTezed ayQ sjeser uotT}oUNF sTyL 
NOILONN4 


qiod TeTTe1ed ayy ezTTeT#TIUTeT —~ jeseyY 
GWWN 


Jasay/ae0TAep’ TeTTe1red 


B - 53 


q1e3S/a0TAap’ TeTTerzed 
OSTW days 


"OJezZ—UOU eq T[TTM TOTIq 3YyR ‘peTTey doys sey} jI 
“T[Tnu eq T[T TOIIq ‘pepesdsons doys ey Jt —- AOA 


SLTNSAY 
dOLs CWO pueullioD OT 
aotAequado Aq jes 3TtTun OT 
aotAaequedo Aq jes @oTAed OT 
pezT[Tetytut yr0gATdaey uu obessop OT 
LSanNOdY OI 


‘aouenbes buTyeyspuey syy Hbutnutjzucostp Aq soTAep 
TeTTezed eyA uo ARZtaAT}Oe O/I 4USeTANS |y sqzTeYy uoTZoUNF STUL 
NOILONNA 


jaiod [aTTered ayy uo ARtatRJoe WuerANo asned —- dos 
WYN 


dojs/aotaep’ TeTTered 


dojs/eotaep * TeTTered 


OSTW ddS 
"O19Z-—UuOoU eq TTTM 1OIIG oy} ‘peT Tey WeIS ayy JI 

‘[T[Nu eq T[TTM TOIITqA ‘/‘pepesodons 3ITeIS |YyW JT -- AOITIY 
SLINSdY 

LYWLS CWO pueuloD OT 

aoTtasquedo Aq jes 4tun oT 

aotasequedo Aq jes SOTASC OT 

pezTTetytut yIogATdey uu aebessayW OT 
LSANOAY OI 


‘aouenbes butyeyspuey ey} butzeatjoeser Aq WA0d 
TettTered ey uo ARTAT}OR O/I WeTINdD |y SsjTe}SeT UOTIOUNF STUL 
NOTLONNA 


q1iod [eTTe1zed ay} uo pesned sey 7eYyR O/I Weqyser —-- WeIS 
GWYWN 


IPAS /soTAap' TeTTe1zed 


o4 


24 1TIM/eo0TAap ‘ IajuTid 
dojs/aotaep *rejuTId 
qiej4s/eotasp ‘rejuTId 
qasay/aotaoap ‘rejuTad 
OUTIMMeY/aoTASp ‘ TejuTAd 
puewlion I d/acotaap ’ rejutaid 
pTTeaAul/aotaap ‘ 1a3uTAd 
ysn{d/aotaep ‘ rejutid 
jr0gudumg/ao0Taep ‘103uTId 


sjuaqU0D 


sweregjes/aotaap’ Tettered ‘/olutbeg/aotaap’ Tattered 
OSTW dds 


-OIONZ—UOU Sq T[TM AOTITW 3y ‘/peTTey 93TIM eYyy JI 


‘[T[Nu aq [TTA 1011q ‘pepesoons 3a4T1M ey} JT -- org 
SLTASAY 
ZTusuer} OF beep JO YOOT Oj} JajUtTOd eyeq OT 
petejunoous JFod [t}#UN puss [- 0} 
qos JT 1O /4TwWSUeTR OF STAa}ORTeYO Jo TequmuU yqzbueT OT 
peltsep pue eTqtssod st O/I yotnb JT WOINS AOI sbeTq OT 
ALIYM CWO pueuUoD OT 
aotaequedo Aq jas 3Tun OT 
aotasquedo Aq jes @oTAed OT 
peztTetqytut yrogATdey uw abessow OT 
LSANOFTY OL 


‘(9OxQ ATRUeTIND) peTeRZUNOCOUS ST AOW ue 

Ttjzun jues ST yNnd3Zno aseod YOTYM UT ‘pasn sT T- sseTun ‘yuqbueT oT 

UI peTjToeds st sxzexSereyo Jo Tequmu ey, “1eqsTber yndjno TeTTe1red 

dUj OF U8z4TIM aq OF SIa}ORTeYO JO weeIjs e sesneod UuoT}OUNT STUL 
NOILONNA 


310d TeTTezred 03 3ndyAno puss —— 33TIM 
GWYN 


97 TIM/e0TAap * Tat Terzed 


LD 
LD 
OQ 


‘antq st ueko pue ‘/usaerb st ejuebeu 
‘pet st moTTaA ‘‘a't ‘ATaatzoedser qOu OF aqjenbs suotjouNy O° Tepuer 
oTjtoeds_reyutid sy} ut senTea OWA ey} ‘410ddns Jayutid gqoy¥ 104 
HONI Udd SSNIT / HLONAT = LHOSIGH (q 
HONI Udd SUSLOWNWHO / (1 + NISUWW LdgT — NIOYWN LHOIY) = HIM (e 
:HUTMOTTTOJ eu Aq pepunog pue sTexTd jo suite} UT ST JejutTIid ayy 
uo eaze aTqejutTad oy jo qUubtey pue YRpPTM oy Fey} 9}OU oesesTd 
‘4QnojuTId Te4sey e seseod sUOS UT 
pue ainjotd JeueetTo yonu e seonpoid sty} /TeuoTjoOerTptTun 
qoeTes ‘TeuOoT}OSeITpTq XO —Tun oq ued ToeqUTAd oY} FI 
‘3~T asn ‘uotqdo Jeyjnq ynduTt ue sey Jazutid ayy jI 
‘QUO YORTG e eSN :UOgqqTI TOTOO e YIM eseyy 4UuTId 
qouueo 0Z oReWTYO eUuy /ATTeOT}FTOeds —- saanjotd aTeos—Aaeirb 
IO oiTUM pue YoeTq ZUTId oF aTqe oq jou Aeu sieqjutid TOTO) 
-pueumioo sty} esn 03 ARTTTqedeo 
sotydeib aaey 4snu saoueZejeid UT pejoeTes iJaqutid suL 


S.LNIH 


(c°o seatbh yotym ~@ / |T-| worjy peatiep st xZ/T) ‘oT jer 
qoedse zodoid ayy ut eanqjotd YOIWW 244 XZ/T eq TTT!” 
aimjotd pajutad ey} uey} Z=smouzsed ¥ T-=STOD}sSed FT (7 
(0°Z SeaTb yotum T / | z-| WOIJ PeATIep ST xz) “oT Wer 
joodse rzedoid ay} uT pue omnjotd YOIWW ey XZ oq TTTM 
aimjotd peqzutid ey uey} [T=smMouzsed ¥ @-=STOO}sSed JT (T 
:saTdurexs 3aulos 
-OTJeI YoOodse Tadoid ayy UT sMoyzsed / | sToo3sed | 
uoT}OeIJ ayy UO peseq UOoTSUedxe ATO UOT JONper 
e TayuTE ST ommqotd TeuTy ayy — O<sMoYyjsed IO Q>STOD3Sed (a 
“Q=SMou;Sed pue 00G=STODFSed 9sn 
‘39aTI0D OT}PeT Qoedse pue apTma sTextd 00g ST 7eUR ein otd 
e artsap nok jt /‘a't /ZaqutTrd ayz Jo oT}zeT Yoodse sy} UO 
poseq jutTid 0} seuTT Jo requmu Zedoid ayy seuTuajep TeATIp 
au3 pue UPTM peTjtoeds ay esn — Q=SMOYRSsed? 0<STODWsed (Pp 
‘sobewrstbew pue /3yerDoTYydery ‘jZUTegexnTed se we2rbo1d 
yons Aq epeul [Teo ay ST STY} ‘bUTRTIM STUY JO SY *9730ON 
PePI9AUT IO pazyIOJSTp you st yeyA eTqrssod eanjotd ysebhreT 
au} UT S}[NseT styl ‘“TeqUTId ay} Jo OTe Yooedse oUy 
uo paseq quTid 03 seUuTT jo ZTequmu dJedoid ey souTuejep 
Taatip oy} 4ydeoxe aaogqe se sures — (Q=SMoYy Sed 3 0=STOD Sed (o 
‘ubty SjOp 00Z pue oq ueo 4T Se aptm se Jequtad 
ouji uo reodde [[T aeInjotd ayy uPYy 007T=SMONSed pue 
0=STooIsed JI /‘a°T ‘sauT[T smoyqzseq qutTid pue suumToo jo 
qequnu umutxeul s,ZajuTId ayy asn — Q<SMoyysed 3 0=STOD3Sed (q 
“sq0p OOZXOZE se requTid ey} uo azvedde [TIM 
ammyzotd ayy yey sueeUl 00Z=SMONISed ¥ OZE=STOOWSEd ‘°9'T 
-SonTeA aynjTosqe se asn — Q¢<smoyj}sed ¥ O<STODysed (e 
raze (Q SI TWIOddS OI AI AINO LOSdda FIWL HOIHM) 
S[TOo seq OT pue SMOYySeqd OT TOF saTn1 [etoods eyL 


"[Tetoeds ot jo aebesn peutoj [Tem YyATIM saTni Tsyy{O 
asoyu} Teb6T13 WOU T[TTM Jesn ayL “ARTTTQezedwoo Io} poutejor 
useq eaey AouL ‘o1ez ST [eToeds oT pue orez ueYyy Tazeerb jou 
aie KoujR usayM S3[Nser peqyoedxeun asonpord Aew 3zeyW S[TOD3Sed OT 


pue SMOYYSOd OT jo uoTjejeId194UT 2yu4 TOJ seTnrA ASTX9 VIOUL 


‘Jaded ay} uo pee jUsD 

eq T[TTM eimqjotd sayz uey} ‘}eS ST YALNED IWIOddS FT 

‘AQTTenb YaALLaT yatma tdp og{ pue Aqttenb Lavud 

0} eS ST SaodUeZTejorid oy Jt tdp OQOT OF Sz Tnejep 

SNId LACYaSVT dH eyL “Tdp SZ 03 Ssq[nejep shemTe 

LaCuaSWT dH eyL “ATeaT Oedser 

‘Tdp OO€ 3 OST ‘OOT ‘SL Ae SAT ZTSUAapP 

ay} ‘siZequTid om} esey} TOF ‘SsNId LaruaswT dH 

ayy pue LACYaSvT dH ey} ere siNnjeaej 

STYy} Hutzroddns se[npou otjytoeds—rejutid ayy 

‘BUTITIM STUY} JO Sy ‘eUO Z[NeJep ayy ueyy (Tdp) 

Ajtsuep yout red sjop juerTayjJtp e Hbutjoeyes 

Jo uotj#do ayy sey TeaATtAp oTFtoeds—raqutid 

ayy ‘32S ST (F-T)ALISNSG IwWloOgdds JI 

‘sTextd rajutad ut patytoeds st reqjeurered 

eau} ‘TeaTO ere uUOTSUSUTp e TOF S4tq [Te JI 

“jutid ayy Jo oT4er 

qoedse ay earesaid 0} peonpez oq Aeul 

SUOTSUSUTp oY4} JO aUO ‘eS ST LOAdSW JI 

“UOTSUSUTp 3eYyR TOF wumutxeul sy JO 

uoT}OeAZ ATeUTGC PTOMHUOCT ke oq OF USYeR 

ST Jojouezed oy} /}eS ST OWYd IWIOSdS JI 

“(SsSeT ST ZTeAcsyoOTYM /SRTWTT UuoTJeINHTjuoo 

ay} TO sytut{T reqyutid ayW Aq pouTuejzep 

se) e[Tqtssod umutxeul ay} OF 3eS ST 

UOCTSUSUTp ayy ueyR ‘JES ST TINA TWIOddS FI 

‘Jaqutid ayA uo YouT ue 

JO su}puesnoyy UT peTytToeds st Aejourered 

peyetoosse oy} uey} ‘eS ST TIW TwIOddS FI 
:Slajourered ysaq Jo uoTjejZeArdraAuT (e Tetoeds oT 


*MOTEq 
peqtiosep se ‘/1aquTid ay} uo oF A3UTId OF Pere 
aU} JO aZIS ey eqTAzosep sAajourered OM} Vsseyy SMOYISEed OT 


STOD}SEd OT 
pojutid eq 03 3IOg}sey ay} UT azTs A 9y} qYPTeHOIAS OT 


peqjutid aq OF 4TOgG}SeYy BY} UT 2ZTS X 3YR UFPTMOIS OT 
Hod}sey ay} OJUT Yossjo A 9yA ROIS OT 
qZIog}sey oyu OFUT Yoszjo xX oy XOIS OT 

O18Z eq p[TNous pue peATesez st prom Jeddn ayy 
eimmjyoni4s WOGMeTA e& WOTJ se He[T} ,Sepoul, ey SOpoW OT 
‘dewrioToo e 03 143d deWiOTOD OT 
"qrog3sey e OF 13d yIogzsey OT 
aTqtssod st O/I yotnb Jt eS WOINO AOI sbeTyq OT 
LYOdudWnd ddd pueuwog OT 
aTqtssod you st O/I yotnb jt yes ywogATdey uw abessay] OT 

LSANOdY OI 


soouatejyetig rTeq4uTid sey 

UT peTytToeds se ‘uoT}eUOJUT HutTeos pue uoTtytsod ‘dep_aroyjpoD 

pettddns oy butsn ‘yIOgG}sey pet{ddns sy} Jo uot Tpuer e sjUuTid 
NOLDLONN A 


qajutid sotyudeib e 03 Wogdzsey petftoaeds ayy dump -— 320qyudumqd 
AWYN 


qZrIogudumd/ao Taap ‘ 198}uTAd 


B - 56 


@Tqtssod st O/I yotnb jt jes YDINO AOI sbhe[yq OT 

CGIIVANI CWO pueuliod OT 

aTqtssod jou st O/I yotnb jt yes WrogATdey uM abessay OT 
LSanoau OI 


‘ATeqyetadordde 1z017a 
SOTASp ay} S}eS pue puPUMIOD PTTeRAUT Ue SAeMTe ST PTTeAUI 
NOIDONNA 


pueullod PT[eAUT — PTTRAU] 
HWWN 


ptTeaul /aotaap ‘raqutTAd 


57 


aTqtssod st O/I yotnb JT jes YOINO dol sbeTd OT 

HSNTd CWO pueuMloD OT 

aoTaaequedo 07 TTeo ey} Aq yoserd BoTAad OT 

aTqtssod jou st O/I yotnb JT jes qrIogA{dey uw abessop OT 
LSANOdU OI 


"4yrun ay 32 O/I peddojs [Te syroge ysnTd 
NOTZLONNA 


(azeTpoumt) sqsenbexr O/I [Te }rOGe —- YsNyA 
AWWN 


ysn{T q/aoTaep ‘tejutTid 


Zaqutid ey} OF 34TImM Of SaqZAq mMeT 9yA 

ezeq OT ut saqdq Jo ATequmuU ayy 

etTqtssod st O/I yotnb JT es YOINO AOI 
ALIUMMYY dud 

aTqtssod you st O/I yotnb Jt yes WodATdey uw 


ejeq OT 
yybueT oT 
sbeTq OT 
puewoD OT 
abessay OT 
LSNOdUY OI 


"31 03 pessed ejep ayy uo butTssaoDo1d 
ou suuojied }eyR pueUMOO 3O4T1IM pepuejsuoU e ST STUL 


NOILONNA 


pueuLOo O4TIM yUeTedsueIA — OaTIMMeY 


GWYN 


OU TIMMeY/a0TASp * 19e3UTId 


Soouerejetg ‘aotaep’TeTTezed ‘y-requtid 031IM/eoTtAep requtTid 


OSTW dus 
00 
-Olaz—uoU oq T[TM TOTTYG ey ‘eSTMTSYAO > 
‘O18Z aq [TIM TOIIG ‘pepesdons puewllon ddd ey} JT *srtorwy : 
SLInasaY ee 
pueuwiod ay} TOF Aajouered ¢uIeg OT 
pueulloo ey} ATOZ Tajeuered ZuUIeg OT 
pueulloo ay} AOJ Tae jeurered Twured OT 
pueuwiod ay} TO} Iajzourered Quieg OT 
Jequnu pueuwoos [enjoe 3y} pueumloDjId OT 
CNWWNOODLYd dud PUeULUOD OT 
aotaequedo Aq yoesead 4tun OT 
aotaaquedo Aq jeseid BoTASd OT 
Jes qIogA{Tdey uu abessay OT 


beypuoyzIdOL LSANOSU OI 


“suoTqzouny [Te Woddns jou Aeu 

sio\utid [TW ‘pueumiod a3TIM/acTAep Tejutid ey} YRTM punoj aq 

ued pezroddns spueumoo ey, ‘“TezUTAd QueTIND ey JO jes apoo 

[Tor}UuO0D ay} OF pueUMICO STU} SdeUl SsoTASep TejUTId syL ~“eoTAEp 

[eties IO TeTTered ayy TayzTe 0} pueuMloo e spues UOT }OUNJ STUL 
NOTDLONNa 


Zajutid ay} OF pueuMlod e pues —— pueUMlodjtddd 
AWWN 


pueulon}Id/a0TAap ‘ IequtTid 


eTqtssod st O/I yotnb jt jes YOIND AOI sbeTq OT 

LYWLS dWo pueuwliod OT 

a0Taaquedg 03 [Teo ayW Aq Aesard BOTAN OT 

eTqtssod jou st O/I yotnb Jt yes yIogATdey uw obessay OT 
LSANOUY OI 


“pueuuioo dojs e Iezye 3TUN 93Uuy S}IeASaeT 7IeIS 
NOITDLONNA 


(azeTpoumiT) dojJs Taqye Arejsezr —- yIeIS 
AWN 


31e4S/a0TAap * raqUTAd 


atqtssod st O/I yoTNb Jt 3s WOINO AO! sbeTq OT 

Lasau aWo PpUeURLOD OT 

aotaaquedo 03 [Teo ey} Aq jeserd BOTAN OT 

aTqtssod jou st O/I Yyotnb JT jes yrogATdey uu abessow OT 
LSHnoOdd OI 


“a0TAep uado ayy OF 
seTpuey butkor4sep yNoyRTM eoTAap IequTAd ey} sjeser jJesoy 
NOTLLONNA 


Iajutid ay} yesez — Jesoey 
aWWN 


Jesay/s0TAep ‘18eUTAd 


B - 59 


JJO pebirertua 

uo pebiertue 

JJO poesuspuoco 

uO SUTJ PesuUepUod 
JFO 9ATTS 

uo aRTTe 

yo3utd [Teuou 


IOTOO punorbyoeq jes 
IOTOO punorbero0Ojy yes 
FJO BOeFPTOR 


uO aoeJPToOd 
JJO oUuTTIepuNn 


uo eUTTIepun 
JJO SOTTRRT 
uO SOTTe4T 
yas eyo Teutou 


JT esireao1r 
JT‘ urnjor 
+1 
ozTleryrur 
jZoesolr 


MG JOS 
ag]osd 
me) Osa 
My) OS 
MT )]OSa 
AZ)OSa 
MOQ JOS 


6¢-OFUDS 
6£-O£€NDS 
wzz] Osa 
wT josa 
wz] OSa 
wy] Sa 
we Z)OSa 
we} Sa 
wo ]dsa 


WOSd 
aOSd 
dosd 
T#0Sa4 
00S 


G¢ dyOHSe 
9dYOHSP 
€ dYOHS® 
¥dyOHSe 
TdudOHSse 
CTdyOHSP 
QdYOHS® 


odse 
OASe 
ZEUOSe 
Tuose 
ycuose 
puose 
€7UOSe 
cuose 
QUuDse 


Tue 
TGNe 
ante 
Niue 
srue 


SCONWNWOD eTAIS #9°EX ISNW 


Ssoouatajerlg ‘a0TAep‘ [eres ‘aotaep’TeTtTered /y*requtid 


OSTW dads 


“OTeZ—UOCU aq [ITM 1ToTIq 3ayQ ‘aeSTMTaYAO 
‘O18Z eq TTIM TOIIq ‘pepesdons a4TAMOd ey JT :sro0r7Tg 


SLINSdAY 
ssa00id 0} ejep Jo YOOTq 03 AaqjUTOd ejed OT 
poreyunoosus Jog [tTqun ssa0o0id /T- 
Jt to ‘ssad0id 0} SiazZoeTeYyd Jo Jequmu yuybueT oT 
ALIYM CWO pueuod OT 
aotasequedg Aq yoseid 3TuN OT 
asoTaequedo Aq jyoesead BOTAed OT 
Jes WogATdey uw abessopW OT 
LSanogd OI 
*suoTjounyJ 


TTe woddns jou Aew sxaqutzd [Tw ‘“MoTeq punoj eq ued pe zroddns 
Sepood ISNWY e4L “TequTId jueTIMdD 9yW JO Yes apod ToOT}UOD sy OF 
Sepod [oT}UCO Ae\UTAd 3Iq-/ STARS P9°EX ISNW Sdeul ‘eOTASp aToOsUOoD 
OU} eYTT ‘aeotasp AZaejutTAd sy], ‘pere\uNOoOUS ST OOXO B [TUN puUsS 

ST jnd3no ased YyoTYM UT ‘pasn ST [— sseTun ‘yybueT OT uT paTytoads 
ST SIazoOeTeyO Jo Jequmu eyL ‘“eoTAep [elias IO TaeTTer1ed syy TeyjTe 
ay} OF U8}z}TIM aq 0} SIAVZOeTeYO JO IJajjnq e sasneo uoTZOUNS STUL 


NOILLONNA 


Zajutid ayy oF YNdA4Nno pues —— 3}TIMOd 


AWN 


94 TIM/e0TAap * TejutTIid 


atqtssod st O/I yotnb JT yos YOINO AO! 

dOLS CANO 

aoTaequado 03 [Teo ey Aq yesaid 

aTqtssod jou st O/I yotnb JT Ayes WOdATdey wu 


B - 60 


sbeTa OT 
puewuog) OT 
SOTASd OT 
abessayl OT 
LSanoau O1 


“pueuuioo dojs oy} raze O/I 

au} USTUTJ pue /YsSNTJ ’31e4S OF SSOY} SepnToOUT YoOTYM ‘sysenbe2z 
O/I a}zeTpeuut aie ATjUenbesqns peutojized aq OF paMoTTe aq 
TTTM 2ey} Spueumioo ATUO ey, “yJsenber O/]I yueTIMdD eyy esned 
0} SeTI} pue yTunN ay} IO} sqysanbez penenb [Te sesned dos 


NOI LONNA 


(ayeTpouut) szsonbezr O/I penenb pue juerImMd oasned — do js 


WYN 


dojs/aotaap’ 1e4uT1d 


SPUPURIOD papuaz xe 
sqe} }[Nejep 3s 


X,Ud]OSa 
G#OSH 


CNA LXae 
TTWSALe 


sqe} A ¥ YU TT® ITO 
sqe} A TIP ITO 
sqe} TeOT}IEA ITO 
qe} U TTR reeToO 
qe} ztzr0ey ATO 
Sqej [TeRoOTATOA 49S 
qe} zTroy 32s 


sutbiew IeaToO 
uTHreU YVT 
sutbreul gy 

Jes hHrew woz Og 
yes utbrew doy 
joes utThxzeu ZYUbTY 
qos utbzreu 4jeqT 


jyo dtys jaed 
(o<u) u dtys jaed 
uU YyybUeT wWIOJ Jos 
putoeds suTT 19/1 
butoeds SuTT .8/T 


(To ZUSsD OBNe) TIT} pzoMm 
(Ajtqasn£C) ooeds ra eT 
yo AZtysnf ojne 
Ajtasn€ [TNF o4ne 
Ajtasn€ qybtz ojne 
Ajtysn€ AyeT o4ne 
ZesfJjJo TeuotjAIOdord Aes 
ieatTo Teuotj1z0doe1d 

Jyo [euotyAz10do1d 

uo [TeucT AOdoCId 


Jes TeYyoO II ustueqd 
qes Teyo uetTbaemion 
joes Teyo ssouedec 
jes Teyuo ystueds 
joes TeYO uUeTTeRI 
jes AeYO uUapemMs 
jes Teyo J ystued 
jes TeUuo YN 

Jes TeUo uUeULTAay 
Jes rAeYyoO Yyousezy 
Jes reyo sn 


UuMOp SeUTT Tet zed 
dn out{T [Tetzzed 
SUTT ey} ezZTTewroOU 
JyJO 3dtTzOsqns 

uo 3dtzosqns 

JJO 4dtz0szedns 

uo 3dtzo0siedns 


JJO OIN 
uo COIN 
FJO SYTASSTQnop 
uo d\yT1IZSeTqnop 
JyJO jZutTId mMopeys 
uo jUTId MOpeYs 


fH fy Ga fy fe a 


vHOSa 
6,) Osa 
BTJosa 
Be josa 
60]Osa 
rosa 
HOS 


€#0S4 


Scud‘ TUd]DS4 
IZud‘ [Ud] DS 


c40SA 
8#0Sd 
O#0SH 
6#0S4 


bo]osa 
bu]osg 
3U) DSH 
ZT JOsa 
Z0)]0Sa 


T]osd 
€]osa 
0]Osa 
9]OSa 
L)osa 
G]osa 
ujosa 
do]osa 
d{]osga 
dzjosa 


2)osa 
9)osSa 
C)osa 
Z OS 
4)OSa 
H)osa 
q)OSa 
W)OSA 
W)Osa 
Wd)osa 
q@)osa 


wosa 

Tosa 
AQ]OSda 
Ag€)Osa 
Ap)Osda 
ATJOSa 
AZ] OSa 


Z,TJOSa 
Zn7]OSA 
Zu€)OSa 
Zy¥] OSH 
ZS JOsSd 
Z,9)OSH 


TIWOELe 


pOaLe 
ToaLe 
COaLe 
QOdLP 
SLAP 
SLHe 


WvO0e 
WYISe 
WaLSe 

SWde 

SW.LP 

swue 

SWTe 


Odddde 
Adade 
dd1se 

TdudAke 

OduydAP 


TAALe 
CAALCLES 
OAALCe 
9AALCEC 
LAACE 
cA re 

SSLe 
QdOuddP 
TdOude 
cdOUde 


OTLNAe 
6LNAe 
BLNAe 
LINAe 
9LNAe 
GINAe 
PINAP 
CLNAe 
C.LNAe 
TINAe 
OLNAS 


@Ide 

NTde 
osnse 
esnse 
ySnse 
Tsnse 
csnse 


TNdde 
CNAde 
€Nade 
pNAde 
GNdde 
Q9Ndde 


61 


‘O1aZ oq TTTM TorTIg ay ‘peTTey Woqy euy FI ‘(shea OT 
JO G 3Tq 3S) peqtoge se pebbeT}F eq TTT jsonber ayy pue (Z-) 


GALNOdY NYAOT# Sq [ITM ToITG ‘pepesoons Yroqy eyy JT —- 101g 
SLTINSdAY 


-pezloge eq 0} ST ey} YOOTA 3SbyoOI eyy OF Zaqutod ——  ysenbeyot 
SLAdNI 


‘peaousi AtssetTuted st 31 ‘penenb 
ST ysoenber ayy JI ‘ATezetpoumt peddojs st FT “aaTqQoe ST ysonber 


au} JI ‘}Senber 2o3TIM IO pear petytoeds ey} s}toge uoTzounZ STUL 
NOI DONNA 


ysonber O/I petytoeds ayy pode —— OIHoqv 
AWWN 


OI Moqy/a2oTaap’ Tet1z1es 


BITIM/ae0TAap ‘ TeTres 
dojS/ecotasp * Tetras 
qIeIS/a0TAap’ Tetras 
sueriedjzes/aotaep : Tetras 
Joesay/a0TAaep’ TeT1es 
peary/a0tasp’ [eT1es 
AranO/aotaep* Tetres 
uedO/so0TAap ’ TeTties 
USNTA/eso0TAsp’ TeTres 
BSOTD/s0TASp’ TeT1zes 
IedaTD/sotTasp: Tet19es 
yeailg/aoTAep’ [TeTres 
O[UTbeg/aoTaap’ Teties 
OIMoqy/ao0Taap’ Teties 
$s jue {U0D 


B - 62 


-OIezZ—UOCU aq T[TM TOIIG Sy ‘pEeTTey Yyeerg euyy FI 


-T[nu oq T[ITM AorIG ‘pepesoons Yeertg ey} JT -—- AoA 
SLINSHY 

uot}dtz9sep eaoqe Jed yOINO OI 3eser/jes sbeTq OT 

wwaud dWods pueulloD OT 

aotaequedo Aq joes qtun OT 

aotaequedo Aq jes BOTAN OT 


abessayW OT 
LSanOdd OL 


poeztTetytut ywogATdey uu 


‘oWe ‘LYWLS ‘dOLS ‘HSNTA 

‘Iyogdw se yons spueumioo Tedoid ey} Y4TM suOoT UEe{UT Tey/sTYy 

a}eUTPIOOS OF} TeTTeo ey} 03 dn ST WI “peqeTduico st uoT}einp 

au} tajje [eubTs oy} SenuTAUOCOSTp ToeWT} oy} pue ‘TeTTeo 

ayy OF SUIN}eET TOTRUOO ‘/ATEe}eTpSUMIT po TeRS ST Yyeoelq eyy 

‘yas JOU ST 41qQ WudGHNENO euy JI “UIN} UT peyNndexe pue enonb 

3soenbert—a3TIm ey Jo yoeq ey 3e peoetd st ysoenber oy} ‘YxooTW 

ysonboy OT eu} UT jes ST sbeTqzes OT Jo 4Tq WuadgngNS ey FI 

JI ‘penutjucostp Teubts oy pue yeser sT 3Tq ey. ‘ (SpuodssoIOTW 

0000GZ 3Inejep ‘surezedjes eta aTqetjy{toeds—resn) uotzernp 

e Io3jv “NOoNGW ber Jo 31q wudLuwn eyz butTzWes Aq 

payst{duoooe st sTuL “Wood [TeTres eyZ yno (potied pepuazxe ue Ioj 

MOT P[ey eUTT [etTies) [Teubts yeerq e spues UOT}OUNJ STUL 
NOILONNA 


SaUTT [TeTIes ey} Teao Teubts yeoriq e pues -- yeorg 
aWYWN 


yeolg/ao0Tasp’ [eties 


‘SswATdey eu [TT}UN peyIoder oq 3,U0M sIOTIa O/I SOW 
‘OlazZ—UOU oq [TTTM TOIIg euy ‘peTtTey Olutbeg ey JI 
‘T[Nu eq [TTA 1o1TIG ‘pepeedons OTUTbeg ey} JT —-- 10124 
SLINSAY 


‘uodo 3e adTAed OT ORUT 3nd pue /4TUT 
3e ATINq epou ,aoTaep’TeTIes, ey} OF TequTod -- aponesoTaep 
“SZojourered pertnbez TeyAO s,pueulllod syy Se [TSM se 
‘ssa00id 0} pueuNiIoD OT UT pueUMIOO PT[TRA e HbuTutTejuoo 
/(uoTATUTJap/ezTsS TOJ T* Tetras 9es) @ZTSIOSAXY OT 
aZTS JO yooTa ysenbey O/I ue oF Iayutod -——  ysenbseyot 
SLNdNI 


-aseo sty} ut ARTATROR ATq TeUubTS 1o HswATdey 
OU ST aay, “AeTTeo ayy OF SUIN}eET 4T SsUTF 944 Aq pe jetduoo st 
AZsonbez au pue pareaeTo jou ST beTjJ YOINO OI euy ‘’eseo sty ul 
-ATezetpouut ysenbey O/I styy 
AJst}es 03 Tayjnq yndut eyW ut ejep ybnouse Apeoeryte ST sTSYL - 
sjisonber peer butpued ou ore sezSYyL —- 
qes ST 31q WOINO OI - 
:USYUM SGWEY TOF st 
SojTIM pue speer jo but[Tpuey YOINoO-uou sty oF uot3daoxe ATuO syuL 
‘butnenb OdIad eTA peTpuey oe sqsonbei eTdt3z [nw 
“auTqQnor HswATdey prepuejs oy eTA poeTeubts st uotjetduop 
*peqetTducs jou ‘unbeq se JaT[eo eyy OF UIN}eT SNYyF pue olutTbeg 
kq peqetqtut ATezeul are soqTim pue spear ‘uoTjdeoxe |euo YIM 
"YOINO OI se pouwrtojied aq ued suoT}oUNJ 9yQ ‘pe zoSTes 
OS JT ‘a0uaH *(SaTJINUTAUODSTp payzeToosse ST IO) DTHOT 
but[Tpuey—ydnazequt Aue uo puedep jou op pue Atsnouoryouds 
poeutojzed are suotjounj ey} /24TIM TO pest UrY T9YAO “SOTASP 
Tetras ay} 0} epeu ysonber O/I e sazeTATUT UoTZoOUNF STUL 
NOILONNaA 


ssa00id O/I ue dn y1e4s -- OlUTbeg 
GWWN 


OlUTbeg/a0TAap’ Tetras 


B - 63 


uadO/a0TaAap’ [Teties 
OSTW dds 


uaodo Aq jes ‘/apou soTAep syj AJejUTOd — aponesdTAep 
SLAdNI 


‘paerj St Jayjnq yndut s,a0Taep ay ‘buTsoTo 
uodn ‘aoTAep TeTIes ay} OF SSsadDe oTeM}JOS SaesOTO UOT }OUNF sTUL 
NOIDLONN4 


(SPONSOTASP ) 9OTASG2SSOTO 
SISdONAS 


WIod [eties ey} ssOTO -- asOoTO 
GWYN 


BSOTO/soTAep’ [Tetras 


‘Olaz—UOU aq [TIM IOIIG ayy ‘peTtTey AeeTD eu JI 


‘[[nu eq [[TM 1oIIg ‘papesodons TeeTD ey} JT ~—- AoATY 
SLINSAY 

YWATO CWO PULUMOD OT 

sotasquedo Aq jes 3tugQ oT 

aotaequedo Aq jes @oTAeq OT 

peztTetytut yrogA{dey uw abessay OT 
LSaNOdY OL 

‘sIaqutod rzeyjnq peer s,yIod [eTies ey} sjJesaet uoTJoOUNF STUL 
NOIDLONN4A 

Ssiajjnq yIod [Tetras ey} TeeToO -- Tee 
GWYN 


IeaTO/sotaep’ Tetras 


64 


‘O18z—uOU Bq TTTM TOITY ayQ /peTtTey uedo 3uy JI 


“[[Tnu eq [TT 10TIq ‘pepesoons usedoO ey} JT —-- AOI 
@pou soTAep ey} OF AeqjUTOd —- od 

SLINSAY 
pezoubt — sbeT] 


(aaoqe NOILONAY ees) sbheTqreas OT Jo asn ALON 

*aUuTINOT sdTASequedo ayy Aq 

PEZTTRTFIUT aq OF (UOTATUTJaep/ezTs TOF y‘T Tetras sas) 
@ZTISI9S}XA OT SZTS JO YyoOT ysenbayot ue oF Je juTod — ysenbeyot 


pezoubt — 4tun 
,@2OTASP’ Tetras, butz,s [Te19aRIT 03 AaqutTod — oswreures 
SLNdNI 


‘butuedo erojeq 31q AMIM/ 844 eS PTNoys sy ‘(Tooo }0Id SLY/SLO 

9-ZEzZSuY ‘a'T) Hutyeyspuey oztm—-, WLoOddns of SjUeM TESN 3yy JI 

-3tIuN/aoTAep [TeTies suo ATUO ST aTAaYR BsoUTS ‘0 OF SPTETJ TUN OT 

pue soTAaed OT dy} SAZTTeTRIUT soTAaquado *(uedo aut, 4SsITJ 

au JT ‘z[TNejep 1O) sanTea jUs.eT JsOoU ATEYy} OF peEZT[eT}IUT ore 

SPTEeTJ OTJToeds_[etias [IW “eoTAep ayy Seso[O ToeumMO ayy [TUN 

PAMOTTe ST SSsaeod0e Tey}O OU pUe pejUueIH ST |aSN DATSNTOXS ‘jas 

ST (she[TqIes OT JO G 3Tq) 3Tq SsadDe-peteYys |Yy} SSeTUN “edTAep 

[TeTias ayy OF ssaeooe aTem}jos Jeqysoenber ay} SMOTTeR UOT IOUNJ STUL 
NOILONNS 


(sbeTJ ‘qsonbayot ‘4Tun ‘/aueutas)d0TAsquedo 
SISdONAS 


yiod [ettes suy uedo oF Asenber e -- usedo 
aWWN 


uedO/a0Taap’ Tetras 


-olazZ-—UOU eq TTTM orig eyy ‘peTtTey ysntTd ey JI 
-[[nu eq [[TM 10zIg ‘pepesoons ysNTd eyy FT -—- Torry 


SLTNSAY 
HSNTd CWO pueunlo) OT 
aotaequedg Aq jes 3tTug OT 
aoTtTaequedo Aq jes BOTAed OT 
poztTetytut yrogh{dew uu abessow OT 
LSanodd OI 


‘sqsenber aaT}OR Yooyye WOU T[TM YysNTA “aoTAep TeT4res 
au} Toy senenb ysenbe 3eyTrM pure pest ey sebind uotjounsJ STtuL 
NOILONNA 


qiod [eties ey} 10J sysenber O/I ponenb [Te rAeeTO -—— ysn {A 
SWWN 


YsnTd/ao0 taep’ Tetras 


B - 65 


“OI9Z—UOU oq [TTM TOIIG oy ‘pelTey peey euy jI 


“T[TnNu oq [[TA TOIT ‘papssoons peoy ouQ JT -—— AOI 
SLTINSdY 

ZJajyjnq peer oj} AsjUTOd eed OT 

UT peeT (00X0)TINU [TTR}UN aATadeT [T- 03 

jes JT IO ‘aATaDaT 0} SAdQTeTeYO JO ASequmu ujbueT oT 

peitsep pue etqtssod O/I yotnb JT wWOINd AOI sbeTd OT 

aqwau dwo pueulloD OT 

as0TAequedg Aq jes 4tun OT 

aotaequedg Aq jes BoTASd OT 

peztTetqtut 3z0gA{Tday uw abessay OT 
LSanOad OI 


‘Iaysenber e 0} peyojyedstp oq ued AT [T}UN Aazynq ynduT 

au} UT peToYsS ST ysenbez ou ST aay} YOTYM AOJ AndUL “peaTeoar ST 

(oOX0)T[TNu ue [TRUN pee ST ANdUT ssed YOTUM UT ‘/psesN ST T[- ssaTuNn 

‘uybue] OT UT peTytToeds st szaqyoezeyo Jo Tequmu oy, *“Wod [Tetres 

au} UT pear aq 03 STaVZOeTeYO Jo weelr4s e Sesned uOoTIOUNJ STUL 
NOILONNA 


Hod [eties worj yndut pear -- peoy 
aWWN 


peay/eoTaep’ Teties 


‘OIOeZ—UOU aq [TTM TOIITW ou ‘paTte}y usn{q ey} FI 
‘T[Tnu eq [[TM T0oIIgG ‘/pepeadons AXond ey JT -— 10129 


Siajoereyo Yndut peeruN JO juNCd Oo} Aes Tenyow OT 


peatesot ST-E€T 
peddO-x eatecser ybty el 
peddo-x yTusuezz = =-ybTY TT 
(4andut 3se7eT Se) peATedezT yeorq ubty OT 


(4and3no jUuacer ySOUl) ZUeS Yyeo1mq ybty 6 
MOTJ1aao Jayjng peer ybty 8 asw 
Apesy [eutwzay eed MOT L 
puss o, Apeay MOT 9 
Zoajed Tete) MOT G 
puss OL rTeeToD MOT y 
Apeoy es ezed MOT € 
peartesart MOT Z 
pearesez MOT T 
peatasar MOT 0 asl 
NOLLONOS dAILOW LI SNAeAYS OT 
SLTNSdAY 
(wo) ANAND GWods pueumloD OT 
aoTAequedo Aq jos 4Tun OT 
-20Tasequedo Aq jes SoTASd OT 
peztTTetqrTur yrogA[Tdey uu abessaw OT 
LSANOdN OI 


"Tenqjow OT UT uMOUS ST Tayjnq peer 

S,20TAOp [RTIes eyj uT saqAq peerun Jo Jequmu ey “SsiTeysTber 

pue souT{T 310d [etres ey} Jo snzej}s ayy suINjer uoTIOUNJ STYyL 
NOILLONNA 


snqeqs out{T/zI0d [etzes Arenb —- Arzand 
HWWN 


Artan0/aeo0 taAep’ Tet1as 


B - 66 


yo Aerzzre a3h4q-g perTaepr0O_-butpusosep TIOSW AerIWWUIaL OT 
SPUOCDSSOYOIW UT TeUubTIS yeerq JO uoT YAINp OWT LYIG OT 
(aaoqe [ 90S) *SoqzTIM GNW Speer AOJ oReT pneq pneg OT 
“LSOT GYW YsdANG GIO GHL JO SLNALNOD °44 
‘snuL, “peqzeooTTe eq Oo} suo pazts AT }OeTIOO 
‘MoU e& pue PazeoOTTeep oq OF AeFjnq JUseTAND 
ay} sesned aztIs Tayjnq ut aebueyo Aue :qLON 
(pesn ou) shelTa}Xy_ OT 
Jayjnq yndut jo sayAq ut yybueT ueTjngy OT 
(owT} STYZ Fe pesn JOU YOV/ONT) 
(ATaat}Oedser) SpTeTJ WOW’ ONI‘’ daOx’ NOX 
au} AOJ saenjTea a34q Hututejzuco pTOMbuOCT e IeYUOTO OT 
“uOoTReANHTJUCS ZUeTAND $,adTASp TeTASsS 9Yy WOSTJor OF 
uedo Aq UT peT[T} ere SpTeTy HutmMo[TO} ey} -*ALON 


(dox0) SWWUWdLas awods pueuRlod OT 
aotaequedo Aq jes 4tuq OT 
eotaeduedo Aq jes eoTAeqd OT 

peztTetqztur yr0gATdey uw abessoW OT 
LSanogdd O1 


‘QuowUOTTAUS eATSsUejUT-—AeTdSTp 

zo/pue Hutyseyry—tnu Asnq e ut sunizzZeao jo AAT{Tqtssod ey} pue 
sqjuswertnber butdurejxs—oault} IGIW Jo esneseq ‘ajzetidoiddeut oq ‘TeAemMoy 
‘Keul speet IGIW AJOJ ouoTe TJeATIp styy Hbutsn ‘peysttduoooe ATtTsee st 
Solel IGIW 3e (eUTOJ IGIW UT ApeertTe s,}eyR) e}ep HuTATIM }eYR 2ION 
"4Tq GeIavSIadx ey} jes osTe 

[Tt gqIpDO00d dwu but#Wes ‘Teubts yeorq e Toy Hutyse} pue ‘’sjTq 8g 

uey} TaujO sujbuaeT Jayorreyo ‘Hhuttpuey aqo-x ‘Aqtired Toy syosayo sdtyxs 
stu ‘ATTeotytoeds ‘peeyraac pepssuun sseddq oj sbeTgqies OT Jo 3Tq 
FINOOd GWU euz OS OF paysebbns st AT ‘IGIW unz 0} bHutAT} ore noA JI 
‘pTeTty rorTq OT ey A ut Asngaeqd 1791S 

ONTeA Sy UINJET [T[TM STY FeUR SION “SATIOR ST SOTASP 

aU STTUM [Teo sureregjes e PTA paebueyo oq ued ey} Ta jzoureted 

A[Tuo ay} ST 4TQ GH IaWSIGX eUuUL ‘peTqeuse y[nejep Aq ST AdOX—NOX 
“AATTTqtzedwoo przemdn einsse 

O} O10Z 0} OS oq LSNW pue T°TA UT pesn jou st she[q}xg OT 

"@TS #SseeT Fe oq YSnuU UeTJNY 

Ciiii) “GNWNWOO 

sureiIegjes AHL AG AINO GHONWHO 4G NWO SUALENWYVd YAHLO TIV 

"ST[Teo eotTAequedo ut pesn ore sbheTyiaes OT Jo sztq AYIML pue 

GHUWHS eyUL “sueredjeas 0} TTeO e yNoYyWIM yooTq ysby OT ey UT 
jeserT/jes oq ued SsheT Ares OT Jo sqztq WuaaEHnAHNS pue ACOWAOU SUL 
“snotztqure od 

Keu (ueqsks Asnq e uo AT{Tetoedse) gyze eaogqe O/I snouozryoudse 
‘@ATSNTOUT pneq 000ZEZ Pue ZIT USeeMjJeq ST pneg OT IO} ynduUT PTTeA 


:A[TTeotytoeds 330N 
‘butpued 10 
@AT}OR aTe SozTIM IO speoer Aue JT [Teo sureredjes e Joolor 
TIT 31 ‘eTqestp/etqeue JAIOX-NOX 1IOJ Adeoxg “sdTASp TeTsz9es 
eu IOy siejewerzed shureyo of TaTTeO ay} SMOTTe UOT}OUNF sTUL 


NOILONNA 


YIod Tetres ay} OJ sAajourered obueyo —— sureredjes 


AWYN 


sueleg}es/eoTtaap’ [Tetras 


t~ 
© 
J 
Oo 
-OleZ—UOU Oq T[TM TOITG oy} ‘peTtTejy Woesey oyy JI 
‘[[nu eq [[T ToITG ‘poepesdons yesey ey} JT -- ory 
SLTASHY 
Lasau dWo pueuwliod OT 
sotaequedo Aq jes 4tug OT 
sotTasquedo Aq jes SoTASd OT 
peztTTetqrut zrogA{Tdey uw obessay OT 
LSanodd OI 
‘yOOTq Zsenbeyot ey} UT sanTeaA Jejourered 
yaset oy} seor—Td suoTjounjJ ey, ‘senTea 3[NejJep osutyz dn—jooq 
ITeyy 0} sTeqjouezed pue sheTJ s,WIod oy} sjes pue ‘Teyjnq 
pezts j[Nejap Mou e suTe}Iqo ‘Teyjnq yueTIMd oy} seystnbutTTer 
‘yuazmmo pue penenb yWoq sqsenbez O/I [Te s}Ioqe I “uot ,Tpuco 
peztTetatut ATyserzy syt 0} YIod [eTIes sy} s}eserT uoT oun; STUL 
NOLDLONNA 
yIod [Tetras ayR ezT[eTITuter —— jesoy 
GWYN 


Joesay/aoTAep’ Teties 


dojs/ao0taap’ Tetres 
OSTW dds 


‘Olaz—uoU aq [T[TM TOITW oy ‘peTTey pyeRS 9A JI 
‘T[nu oq [ITM AOIIG ‘papeeoons zIeIS 9eyA FT -— Ao1Ig 


SLTNSAY 
LYWLs GWo pueunloD OT 
aotAaequedo Aq jes 3tun OT 
aotaequedo Aq yes aoTAed OT 
peztTertqrut yogATdey uu abessoy OT 
LSanodd OI 


‘AATaTqoOR QueTIMS 0} a zeTAdoidde usyM/jT ,,’SPTS Ano, OF NOX 

TeoTboT,, e@ HutzAQTwuqns pur ,,/epTs Tey,O, ey} OF NOX ue butpues 

Aq yod [Tetras ayy Uo O/I UeTAND [Te s}Ie,SeT UOT ZoOUNF STUL 
NOITLONNA 


qaod [Tetras ey Tao O/I pesned preset -—— pPIe YS 
GWYN 


31e4S/ae0TAap ‘ TeTres 


‘OeZ—UOU Bq [TTA TOTIWG eYyA ‘peTTey swered}es oy} fI 
‘T[InNu eq [TIM JoIZYy ‘pepssoons sureregjes ey} JT -—- AorzIy 


“SATQAORUT 
Aerzrwuray, pue Toooqord eatm—-¢ ‘/hutyoayo Aqtired 

ou ‘peTqeue—JaO/NOX /Ssseooe aATSNTOXe spTeTAé 

OOX 2eU} ALON ‘Seqenbs 4Tq TOJ Y’T*Tettes ses 

(, => UaeTpesy JI spear AOJZ poetytoeds 

aq ued g ’Teulmou [) s3tq doqs Jo zZequmu 

" " » (8-T) pom azTim ut sztq Jo tequnu 
Ajtied Hbutpnptout jou (g-T) piom peer UT sqztq jo requmuU 
( COELOLOEOEOPOAZTSX ‘°b'e) “Jes ST sbeTj1es OT 

JO 31q aGOWAOd JT ATUO peYOoyo ere srOzJeUTUAL 

“ONTRA PTTeA 4SemoT/m AeTIe Ano [TTF ‘pesn 

Ssreyuo g ueYyy SSeT JI ‘SsTejoereyo uoTtzeutTuse} 


SLTASAY 


sbe[qies OT 


S3tqdojs OT 
Ue@TSRTIM OT 
usTpesy OT 


B - 68 


sueiregjas/aotaep’ Teties ‘Oo[UTbeg/eoTAep’ Tetras 


OSTW duS 
-O1NZ—UOU Sq TTTM TOIAG syW ‘peTtey o3T4AM 9Uy FI 
-[T[TNu aq [[TM ToITWG ‘/pepesaoons o4TIM ey JT —— Torr 
SLTASaY 
jTusuer} OF eJep JO YOOTG OF ATaquUToOd eyzeq OT 
aojjnq UT pereqzunooue [[Nu TTIuUN ATusUeT T- OF 
qos JT TO ‘3TwsueITZ OF SXTaZORTeYO Jo Tequnu yybueT OT 
pertsep pue etqtssod O/I yotnb JT eS WOINO AOI sbeTd OT 
ALTIUM CWO pueullioD OT 
sotTAequedo Aq jes 4tun OT 
sotTAequedo Aq jas aoTAed OT 
pezt[Tetytur yrogA{Tdey uw ebessoW OT 
LSANOFY OI 


‘pezezunosus st (00x0)TInNu e 

[qtjun jues st 3nd3Zno seseo YyoTYM UT ‘pesn ST T- sseTun ‘yqbueT oT 

uI peTJToeds sT sZeqjorrTeyo jo Aequnu sl “yI0d [Tetras 3uy 

4no Uez3zTIM eq 03 SZeqZOeTeYO Jo weor}s e sesneo uoTIOUNZ STUL 
NOTLONNA 


jaiod Tetzes 03 Yndj}no puss — 9 3TIM 
GWYN 


O}TIM/a0TASp’ Tetras 


31e4S/a0TASp’ TeTIes 
OSTW dds 


‘oIaz—uoU eq [TTM TOIIG oy ‘paeTTey dojs euy jI 
-T[nNu eq Tt ToT ‘pepeasons doys ey} JT -- ro01yY 


SLTNSAY 
dOLS CWO pueuoD OT 
aoTaequedo Aq 3es qtug oT 
sotasequedo Aq jes BOTAOd OT 
peztTetyrut wogh{dey wi abessow OT 
LSAnogd OI 


‘AZTAT}IOR Quen 03 aReTAdoidde usyM/jT ,,‘SpTS aN, OF »AdOX 
TeoTboT,, e butAytwqns pur ,,/epts Ty AO, e474 OF AAOX ue butpuses 
Aq y0d [elles ey} uo O/I yuezAINS TTe szTey uoTZouNZ STUyL 
NOLDONNA 


yIod [TeTiIes ey} Teao O/T UEATINS [Te asned —— dos 
GWYN 


dojS/a0TaAep’ Teties 


B - 69 


sond 
OSTW dds 
SNOT Lddoxd 
-soanjonid4s Teast} 0} STaQUTOd -- aDINOS /4Sed 
SLOAdNI 
‘pebueyoun 3JeT oq TTTM TW pue ov 
(seq <— aornos + 3seqd) UOCT}eUTASep ey} UT peTOJS aie Ssz[Nser 
auL ‘“TeyZoue OF eAN}ONTS TeASUITZ 9UO Sppe SUTINOT STUL 
NOILONNA 
OW TW OW 
BoTAep Tout} /( aomosg ‘’4seq )SUTLPPY 
SISdONAS 
ZJaujoue 0} ySenboer ouUIT, |BUO ppe — SUTLPpPV 
AWYN 


SUT LPPW/eoTASp ‘ TeuTy 


AWILLSASLAS UL/SOTASp ‘ TeuUTR 
AWILSASLAD UL/SOTAep " TewTA 
LSANOANddY UL/e0TASp * TowTz 
SUT LNS/a0 TASp * Tout 

auT Ldup/e0TAep * TeulT 3 
punorbyoed/a0 TAap * TaulT 4 
SUT LPpv/20 TAep ‘ TeuIT 
sjua3}U0D 


B - 70 


*peqizoddns are 
uostiedwoo pue ‘/uoT}JOeTAQnS ‘UOCTIIPpwY ‘“SeanjonzySs T[eASUIT 
butjetndtueu roy ore AOUL “ST[eO exTT-AreqmqTyT ‘3oeATTp se1yy 


sqioddns os{Te JewTz ayy ‘/STTeO aoTASp Teutou sy} OF UOCTITppe UI 
AUWAdI'T 


‘(azouU IO puooss Z/T 
At[Teotdk}) aurz jo spotied Hhuo[T TOF Hut Tem ere oYyM asoyy 
Aq pesn oq prnoys pue ‘asn 0} deoeyo ST Tout} aul 


song ‘(pue[ IWd UT SpuocoesotOTU 00002 IO) SpuoosesorTOTU 1999T 
A[Tuo Jo uotyNToser e sey 3ynq ‘sauUTTZ Teao oTqejs Aaa ST 
OSTW das 41 ‘3dnzzezUT yUeTq TeoTzIAEA |YyR Aq USPATIP ST TUN STUL 
MNWITdA LINN 
SNOT Ldgdoxd 


‘queored SATS UTYFTM OF oQeINooeR ATTeoTdAR sT TouUTQ SUL 
qInserz -SoseeIOUT peoT weqsAs se QJTIP TTT ynq ‘spuocossotoTu 


@o0INOS uUey SUT} eTOCUI sey Sed JT T+ = 
eomnos ueYy SUT} SSeT sey 4Seq FT T- = #[nse1 Z ynoqe 0} uMOp uOoTSTOeId sey FI “owt SzT Jo yorzy 
goanos se owt} owes oy, sey 4Sed JT QO = #[NSseT dasy 0 0ZSG8 euQ UT ZeUWT eTqeumerboid e sesn 4TUN STUL 
SLINSaY ZHOMOIN LINA 
‘“semmyzont4s TeASWT OF SIaqzUuTOd —— sdIMOS ‘seq ‘uOTANTOSeT peyTuTT ATuO sey 3ynq ‘aUITF AeAo eTqeys Alaa St 
SLNdNI ‘peayzraao weqshks eTAATT sey ey} TeujO ey ‘a zeIModoOeUT 
43nq estoaid st 3ey} suo —— sqTuUN OM} SUTe UCD TOUT, SUL 
‘pebueyoun 3JeT eq TIT Tw pue ow S.LINN 
“SeINJoNAAS TeASUT} OM} SeTedwod SUT NOT STYL ‘UOTTTTu aUuO pue CQ UaeMjeq oq YSN paombuocT ey ‘/‘5b’a 
NOIDONNA ,{peztTeutou,, oq sAemTe Ysnul SpucdesoTOTU eYyL “SpuodesoToOTU FO 
Jequmnu [eUCTIOeIJ ayy ST 193zWeT SYA ‘Spuodes Jo Jequmu 9yy 
OV TW OW ST 4SITJ OYL ‘SpXOMbUOCT Om} JO S}STSUOD BIN ZONTAS TeASUIT WV 
SoTASp ’Teuty ’( somos ‘’4seq )outIdup = 4ITnsez TWAAW IL 
SISdONAS 
‘aanjoniz3s Teaoutz e Aq peEeMOoTTOJ 
Soeinjoni4s [eAsUT} OM} aTeduioo — sutydup ysonboyor ue sey 3I “~3Ssenbey OI pzepuejsuou e ST ysonbez aut} W 
GWYN LSaAnNOdd YAWIL 


oUTLdup/a0TaAap * Tault3 punorbyoeq/a0 TAap * TeulT} 


B- 71 


yun utequoo [TTA out} 13 
SLINSdAY 
A[det [TTA TatAp su 
[tjzun Huot moy Ajftoads oimjonr,s Teast} e out} 23 
STqeeoTTe WOINS AOI sbeTa OT 
LSanoaUudqw UL pueuoD OT 
aotaequedo ut rewty Aq joesead 3tTun OT 
soTAequedo ut zrewtqz Aq Aosard aoTAed OT 
poeztlTetqzrut yzrogATdey ui abessopW OT 


LSanOsdd YW 


"O19Z OF UMOP SqUNOD JSUT |YyA UeYyA Iesn 

ouy 03 yorq ebessou oy ATder [TT pue sysoenber 

IayjO ST yQTA Asenber sTyy uTeYo T[[TM ASeUT SUL 

‘ouT} JO WZUNOWe peTytoeds e JJO AuNoCdD OF JaUITR OUQ SYXSV 
NOILONNA 


SUT} SUT OF FSenber e yTuqns — LSaAnoaNddW UL 
aWWN 


LSSNOFNdGY UL/eOTASpP * TeuUITA 


sond 
OSTW ddS 
SNOT LddOxd 
-Somnjondys TeAsUT} 0} STaQUTOd —-— sdIMNOS ‘34Seqd 
SLAdNI 
‘pebueyoun 3jeT eq [IT [TW pue OW 
(3Sseq <— aommos — 4Seqd) UOT}eUTASAap 2eYy} UT peToO JS ere Sy[Nser 
auL ‘“Teyjoue worJ aeamnjonIASs T[eaoulT} suo syZoeTRZQns sUT NOT STUL 
NOTLONNA 
OV TW OW 
SoTAep’reutT3 ‘( somos ‘3sSaq )eUTLqns 
SISdONAS 
Zeyjoue wory ysoenber suit} euo yoeTWQnS — sUTLqns 
GWWN 


aUT.LqnS/a0TAap * aut} 


B - 72 


aUT} weySsAS jUeTINS 3A oF 
YTM UT PEeTTTF eq TTT sanqonz4s T[eAoUT oY F ouT} 23 ms 
SLTINSAY cD 
auO0U eTqemoT {Te WOINO AOL sbeTd OT 
SLINSaY LSandaudaw UL PpueUnIoD OT 
aotTaequedo ut reut3 Aq yeserd 3tugq OT 
SUIT aotTAequedo ut zewt} Aq jeserd SOTASd OT 
we sks juezmo ayy YIM einqjoNIAS TeAduUT e out} 13 pezt{TerTytut ywodATdew uu oabessow OT 
STQeMOTTe WOINO JOI sbeTaq OT LSANOdU YWAWLL 
LSANOANdGW UL pueuwioD OT 
aoTaequedo ut xreuty Aq yosord 3tug OT ‘HutjZeederzun pue enbtun st oeut} weyzsks ey} JO onTeaA UIN}eT SYA 
adTAequedo ut rTeutTy Aq yosead BoTASd OT ‘Kem sty} UI ‘ST 4T oUT  ZeEYM Syse suOSWOS suUIT ATeAD 
peztTerqturt yodAtdey uw abessow OT pebueyo ST 4T ‘UOT Tppe UI ‘“TeATequT HbuTyueTq TeoT EA 
LSanOsdd YAWIL ayy Aq yUeTq TeoT TEA AToAS pojUSUETOUT ST SUT} SUL 
-(Spiemyoreq dUIT} ey Sj}eS suUCESUlIOS JT 4Wdaoxe) enbtun aq 0% 
‘butseazout ATTeotTuojZouou Huteq se petjtoeds st poajueienb pue butseezout ATTeoTuC JOUCU ST SUIT wWeySdhS 
ouT wexSkS ‘“SpTeMyoeq dsUIT} OY} HuTIWeSs USYyM 
uayxe} oq PTNOYS sTeD ‘TSAeMOH “SUIT ,, [eeT, SY} OF PTeMIOFJ ‘[TT@O AWILSASLYS UL 
}T 20S 073 SJes ST AT OS ,,OTOEZ,, SUTR Fe YNO SsjzTe WS SU} PTA pezTTetytTut oq Aeul 4nq uo-ZTaemod ze oOTeZ je 
wo3shs oyL “ST 3T SUT} }eyM Jo eaepT s,ue ISAS ay} SOS sqieqs owt} we3xsks oyL “ST 4T owt} }eYyM ToeUT SY} S{SW 
NOIDLONNA NOTLONNa 
aut} weqsks ay} 32S -- AWILSASLES UL ouT} we}sks ay} web —— AWILSASLED UL 
GWYN aAWWN 


AWILSASLAS UL/SOTAep * TSuTR AWILSASLAD UL/POTASp * ToulTy 


Appendix C 


Resource Summaries 


This appendix contains summaries for system resource routines. Resources are software entities 
in the Amiga kernel software that enable cooperating tasks to gain exclusive access to certain 
parts of the Amiga hardware. There are four resources in the Amiga system: 


disk allows access to one of four possible disk units. 


cla allows you to access specific bits in each of the Complex Interface Adapters. 


There are two cia resources: ciaa.resource and ciab.resource, corresponding to the 
first and second 8520 in the system. See the software memory map in Amiga ROM 


Kernel Reference Manual: Exec for the definition of the bits controlled by each 
cla. 


potgo manages the bits of the POTGO register. 


misc manages the serial and parallel port register bits. 
Each routine for resource management is outlined in the summary sections that follow. 


Note: Resources need be used only if you are attempting to use the associated hardware 
directly. The system software routines use these resources internally when they perform 
hardware operations. Tasks that also use these software resource controls will be compatible 
with Exec and the system software. 


To use the routines listed for the resources, you must first open the resource and assign the 
value returned to a specific base pointer name. Here is a list of the resource names and their 
associated base pointer names. Like names for libraries, their names are null-terminated strings: 


Resource Name Base Pointer Name 


potgo.resource PotgoBase 


disk .resource None provided, for assembly-language 
programmers only 


misc.resource None provided, for assembly-language 
programmers only 


claa.resource < user-defined > 


clab.resource < user-defined > 


Some examples follow. 


struct Library *PotgoBase; 


PotgoBase = (struct Library *)OpenResource(” potgo.resource” ); 
/* then use the routines provided */ 


/* <user-defined > example */ 
struct Library *myCiaPointerA; 


myCiaPointerA = (struct Library *)OpenResource(” ciaa.resource” ); 


/* then utilize myCiaPointerA as one of the explicit parameters 
* for the C language calls to the resource routines. */ 
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Appendix D 


Include Files 


This appendix has separate sections for the C and assembly-language include files. At the 
beginning of each section of files there is a cross-reference showing all the defined constants, 


data structures, and data structure terms in each file. These names are listed alphabetically, 
followed by file and line-number references. 


C Include Files— ‘‘.h’’ Files 


The first portion of this appendix contains the C-language include files that define the system 
data structures used by the ROM (or kickstart) routines and the disk-loadable libraries. These 
include files are organized on a functional basis. For example, files pertinent to graphics are 
listed under “graphics/graphicsitem.h.”’ 


This appendix is a hard copy of the “SYS:includes” directory on the Amiga C (Lattice C) disk. 


Assembly-language Include Files— ‘‘.i’”’ Files 


The second portion of this appendix contains the assembly language include files that define the 
system data structures used by the ROM (or kickstart) routines and the disk-loadable libraries. 
These include files are organized on a functional basis. For example, files pertinent to graphics 
are listed under “‘graphics/graphicsitem.i.”’ 


This appendix is a hard copy of the ”SYS:includes” directory on the Amiga Macro Assembler 
disk. 
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File numbers for cross-reference listing: 


l:adkbits.i 2:audio.1 3:blit.i 4:bootblock.i 
S:cia.i 6:ciabase.i 7:clip.i 8:clipboard.i 
9:console.i 10:copper .i ll:custom.i 12:disk.i 


13:diskfont.i 14:display.i 15:dmabits.i 16:dos.i 
17:dos_lib.i 18:dosextens.i 19:gameport.i 20:gels.i 


21:gfx.i 22:gfxbase.i 23:1icon.i 24:input.i 
25: inpucevent.a 26:intbits .1 27:intuition.i 28:intuitionbase.i 
29 :keyboard.i a a 31: layers .i 32:misc.i 
33:narrator.i 34:parallel.i 35:potgo.i 36:printer.i 
37 :prtbase.i 38:rastport.i 39:regions.i 40:serial.i 
4l:sprite.i A42:startup.i A3:text.i 44:timer .i 
45:trackdisk.i 46:translator.i 47:view.i 48 :workbench.i 
A, 16-113, 27-217, 27-549, 27-1235, 27-1443 
ABC, 3-38 
aBMS, 36-113 


ABNC, 3-39 
ABORT, 34-75, 40-72 
absoluted, 27-572, 27-574 
AC, 20-137 
ac_AnimBob, 20-157 
ac_AnimCRoutine, 20-153 
ac_CompFlags, 20-139 
ac_dat, 11-100 
ac_HeadOb, 20-156 
ac_len, 11-97 
ac_NextComp, 20-148 
ac_NextSeq, 20-151 
ac_per, 11-98 
ac_PrevComp, 20-149 
ac_PrevSeq, 20-152 
ac_ptr, 11-96 
ac_SIZE, 20-158 
ac_SIZEOF, 11-101 
ac_Timer, 20-143 
ac_TimeSet, 20-146 
ac_vol, 11-99 
ac_XTrans, 20-155 
ac_YTrans, 20-154 
aCAM, 36-116 
ACCESS_READ, 16-42 
ACCESS_WRITE, 16-44 
ACTION_COPY_DIR, 18-127 
ACTION_CREATE_DIR, 18-130 
ACTION_CURRENT_VOLUME, 18-118 
ACTION_DELETE_OBJECT, 18-124 
ACTION_DIE, 18-116 
ACTION_DISK_CHANGE, 18-141 
ACTION_DISK_INEFO, 18-133 
ACTION_DISK_TYPE, 18-140 
ACTION_EVENT, 18-117 
ACTION_EXAMINE_NEXT, 18-132 
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ACTION_EXAMINE_OBJECT, 18-131 
ACTION_FREE_LOCK, 18-123 
ACTION_GET_BLOCK, 18-114 

ACTION_INEO, 18-134 
ACTION_INHIBIT, 18-139 
ACTION_LOCATE_OBJECT, 18-119 
ACTION_NIL, 18-113 
ACTION_PARENT, 18-137 
ACTION_READ, 18-122 
ACTION_RENAME_DISK, 18-120 
ACTION_RENAME_OBJECT, 18-125 
ACTION_SET_COMMENT, 18-136 
ACTION_SET_MAP, 18-115 
ACTION_SET_PROTECT, 18-129 
CTION_TIMER, 18-138 
ACTION_WAIT_CHAR, 18-128 
ACTION_WRITE, 18-121 
ACTIVATE, 27-1148 
ACTIVE, 12-72, 34-76, 40-73 
ACTIVEWINDOW, 27-932 
actually, 27-1488 
ADALLOC_MAXPREC, 2-19 
ADALLOC_MINPREC, 2-18 
ADCMD_ALLOCATE, 2-29 
ADCMD_FINISH, 2-23 
ADCMD_FREE, 2-21 
ADCMD_LOCK, 2-25 
ADCMD_PERVOL, 2-324 
ADCMD_SETPREC, 2-22 
ADCMD_WAITCYCLE, 2-26 
ADCMDB_NOUNIT, 2-27 
ADCMDF_NOUNIT, 2-28, 2-29 
added, 27-515 
address, 27-1237 
aDEN1, 36-71 
aDEN2, 36-70 
aDEN3, 36-69 
aDEN4, 36-68 
aDENS, 36-67 
aDEN6, 36-66 
ADHARD_CHANNELS, 2-16 
ADIOB_NOWAIT, 2-35 
ADIOB_PERVOL, 2-31 
ADIOB_SYNCCYCLE, 2-33 
ADIOB_WRITEMESSAGE, 2-37 
ADIOERR_ALLOCFAILED, 2-41 
ADIOERR_CHANNELSTOLEN, 2-42 
ADIOERR_NOALLOCATION, 2-40 
ADIOF_NOWAIT, 2-36 
ADIOF_PERVOL, 2-32 
ADIOF_SYNCCYCLE, 2-34 
ADIOF_WRITEMESSAGE, 2-38 
ADKB_FAST, 1-22 
ADKB_MEMPREC, 1-18 
ADKB_MSBSYNC, 1-21 
ADKB_PRECOMP0, 1-17 
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ADKB_PRECOMP1, 
ADKB_SETCLR, 
ADKB_UARTBRK, 
ADKB_USEOP1, 
ADKB_USEOV1, 
ADKB_USE1P2, 
ADKB_USE1V2, 
ADKB_USE 2P3, 
ADKB_USE2V3, 
ADKB_USE3PN, 
ADKB_USE3VN, 
ADKB_WORDSYNC, 
adkcon, 
adkconr, 
ADKE_FAST, 
ADKE_MFMPREC, 
ADKE_MSBSYNC, 
ADKE_PREOOONS, 
ADKF_PRE140NS, 
ADKE_PRE280NS, 
ADKF_PRE560NS, 
ADKF_PRECOMP0, 
ADKFE_PRECOMP1, 
ADKE_SETCLR, 
ADKF_UARTBRK, 
ADKE_USEOP1, 
ADKF_USEOV1, 
ADKFE_USE1P2, 
ADKE_USE1V2, 
ADKF_USE2P3, 
ADKF_USE2V3, 
ADKFE_USE3PN, 
ADKE_USE3VN, 
ADKE_WORDSYNC, 
advance, 
aEXTEND, 

AF 


af_Attr, 
af_SIZEOF, 

af_ , 

H, 

afh_AF , 
afh_NumEntries, 
aENTO, 


aFNT9Y, 
aHTS, 
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ai_Count, 
ai_FirstxX, 
ai_FirstyY, 
ai_FlagPtr, 
ai_FlagTbl, 
ai_MaxCount, 
ai_SIZEOF, 
ai_VctrPtr, 
ai_VctrTbl, 


algorithmic, 
all, 
ALLOCO, 


ALLOC3, 
allocated, 
ALLOWED, 
aLMS, 
ALPHA_P_101, 
ALTKEYMAP, 
ANBC, 
ANBNC, 
aNEL, 
ANFRACSIZE, 
ANIMHALE , 


“Ad, 
ao_AnimORoutine, 
ao_An0Oldx, 
ao_AnOldyY, 
ao_AnXx, 
ao_AnY, 
ao_AUserExt, 
ao_Clock, 
ao_HeadComp, 
ao_NextOb, 
ao_PrevOb, 
ao_RingXTrans, 
ao_RingYTrans, 
ao_SIZEOF, 
ao_XAccel, 
ao_XVel, 
ao_YAccel, 
ao_YVel, 
aPERF, 

aPERFO, 

aPLD, 

aPLU, 


1-16 

1-15 

1-19 

1-26 

1-30 

1-25 

1-29 

1-24 

1-28 

1-23 

1-27 

1-20 

11-87 

11-28 

1-39 

1-35 

1-38 

1-49 

1-50 

SH OL 

1-52 

1-34, 1-50, 1-52 
1-33, 1-51, 1-52 
1-32 
1-36 
1-43 
1-47 
1-42 
1-46 
1-41 
1-45 
1-40 
1-44 
1-37 
27-559 
36-126 
13-60, 
13-65 
13-66 
13-64 
13-68 
13-70 
13-69 
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fib_Comment, 
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fib_Size, 
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FileHandle, 
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FileLock, 
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fl_Key, 
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f£1_SIZEOF, 
f1_Task, 
fl1_Volume, 
flag, 

8, 
EOLLOWMOUSE, 
FontSize, 
four, 
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FREEHORIZ, 
FreeList, 
FreeList_SIZEOE, 
FREEVERT, 

fron, 
ERST_DOT, 
ERST_DOTn, 


ES, 
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function, 
functions, 
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3-69 
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27-614 
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48-92 
18-232 
18-230 
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27-127 
27-849, 27-1044, 
27-436, 27-443 
27-1486 

27-792 


27-1543 


27-237, 27-690, 27-1344 


27-1217 


43-25, 43-26, 43-27, 43-28, 43-29, 43-30, 


43-31, 43-32 
27-583 

48-91 

48-95, 48-121 
27-588 
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27-430 
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27-399 
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Gadget, 


GADGET0002, 
GADGETDOWN , 


gad 
Gad et fype 
E 


ets, 
GADGHBOX, 
GADGHCOMP , 
GADGHIGHBITS, 
GADGHIMAGE , 
GADGHNONE , 
GADGIMAGE , 
GADGIMMEDIATE, 
GamePortTrigger, 
gb_ActiView, 
gb_BeamSync, 
gb_BlitLock, 
gb_BlitNest, 
gb_BlitOwner, 
gb_blitter, 
gb_BlitWaitQ, 
gb_bl thd, 
gb_bltsrv, 
gb_blttl, 
gb_bsblthd, 
gb_bsblttl, 
gb_bytereserved, 
gb_cia, 
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gb_Debug, 

gb_De faultFont, 
gb_DisplayFlags, 
gb_Flags, 

gb_LOF list, 
gb_Modes, 
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gb_SIZE, 
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GELGONE, 
GelsInfo, 
GENLOCK_VIDEO, 
get, 
GetPacket, 
gfx, 

GfxBase, 
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gg_Flags, 


27-289, 
27-506, 
27-651, 
27-493 
27-911 
27-217, 
27-468, 
27-912 
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27-357 
27-356 
27-359 
27-360 
27-365 
27-413 
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22-36 
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47-18 
27-871, 
17-40 
7-9, 
22-19 
27-300 
27-298 


27-333, 27-368, 
27-547, 27-565, 
27-1253 


27-409, 
27-643, 


27-814, 27-1728 
27-473 


27-1730 
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gg_MutualExclude, 
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gg_Specialinfo, 
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i_bottommost, 
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GID_HORIZSCROLL, 
GID_LEFTSCROLL, 
GID_NAME , 
GID_RIGHTSCROLL, 
GID_UPSCROLL, 
GID_VERTSCROLL, 
GID_WBOBJECT, 
GIMMEZEROZERO, 
GPCT_ABSJOYSTICK, 
GPCT_ALLOCATED, 
GPCT_MOUSE, 
GPCT_NOCONTROLLER , 
GPCT_RELJOYSTICK, 
GPD_ASKCTYPE, 


GPD_SETCTYPE, 
GPD_SETTRIGGER, 
GPDERR_SETCTYPE, 
GPT, 

gpt_K 2 
gpt_SIZEOF, 
gpt_Timeout, 
gpt_XDelta, 
gpt_YDelta, 
graphics, 


27-347 

27-309 

27-316 

27-302 

27-296 

27-293 

27-339 

27-291 

27-314 

27-351, 48-54, 48-55, 48-56, 48-57, 48-58, 
48-59, 48-77, 48-120 

27-345 

27-294 

27-348 

27-295 

38-36 

38-32 

38-37 

38-25 

38-26 

38-27 

38-38 

38-31 

38-33 

38-29 

38-34 

38-39 

38-23 

38-35 

48-152 

48-147 

48-149 

48-153 

48-150 

48-151 

48-148 

48-146 

27-1023, 27-1143 

19-46 
19-41 
19-44 
19-42 
19-45 
19-22 
19-24 
19-21 
19-23 
19-25 
19-50 
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19-34 
19-38 
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7-9, 13-20, 27-25, 27-29, 27-33, 27-37, 
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GRELBOTTOM, 
GRELHEIGHT, 
GRELRIGHT, 
GRELWIDTH, 


highlight, 
HIGHNONE, 
HOLDNMODIFY, 

how, 

HP_LASERJET, 
HP_LASERJET_PLUS, 
HSIZEBITS, 
HSIZEMASK, 
ib_ActiveScreen, 
ib_ActiveWindow, 
ib_FirstScreen, 
ib_LibNode, 
ib_ViewLord, 

icon, 

IconDisp, 

ICO ? 

id_ esPerBlock, 
d_DiskState, 

id Dis > 
ID_DOS_DISK, 
id_InUse, 
ID_KICKSTART_DISK, 
ID_NO_DISK_PRESENT, 
ID_NOT_REALLY_DOS, 
id_NumBlocks, 
id_NumBlocksUsed, 
id_NumSoftErrors, 
id_SIZEOE, 
id_UnitNumber, 
ID_UNREADABLE_DISK, 
ID_VALIDATED, 
ID_VALIDATING, 
id_VolumeNode, 
ID_WRITE_PROTECTED, 
IDCMP, 

ie_Class, 

1e_Code, 
ie_EventAddress, 
ie_NextEvent, 
ie_Quali fier, 
ie_SIZEOE, 
ie_SubClass, 


27-41, 27-45, 28-24, 38-10, 39-10, 47-9 
27-377 
27-386 
27-379 
27-383 
27-902, 27-904, 27-927, 27-931, 27-933, 27-935 
27-476 
27-432, 27-790, 27-871, 27-1246, 27-1267 
27-947 
27-174 
27-172 
27-169 
27-171 
27-185 
27-120 
27-176 
14-23 
27-543, 27-545 
27-1641 
27-1642 
3-29 
3-31 
28-51 
28-50 
28-61 
28-48 
28-49 
23-31 
48-128 
23-30 
16-100 
16-97 
16-101 
16-115 
16-103 
16-116 
16-112 
16-114 
16-98 
16-99 
16-95 
16-104 
16-96 
16-113 
16-110 
16-109 
16-102 
16-108 
27-940 
25-135 
25-137 
25-139 
25-134 
25-138 
25-143 
25-136 
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ie_TimeStanmp, 

ie_X, 

ie Y, 
IECLASS_ACTIVEWINDOW, 
IECLASS_CLOSEWINDOW, 
IECLASS_DISKINSERTED, 
IECLASS_DISKREMOVED, 
IECLASS_EVENT, 
IECLASS_GADGETDOWN, 
IECLASS_GADGETUP, 
IECLASS_INACTIVEWINDOW, 
IECLASS_MAX, 
IECLASS_MENULIST, 
IECLASS_NEWPREES, 
IECLASS_NULL, 
IECLASS_POINTERPOS, 
IECLASS_RAWKEY, 
IECLASS_RAWMOUSE, 
IECLASS_REFRESHWINDOW, 
IECLASS_REQUESTER, 
IECLASS_SIZEWINDOW, 
IECLASS_TIMER, 
IECODE_ASCII_DEL, 
IECODE_ASCII_FIRST, 
IECODE_ASCII_LAST, 
IECODE_CO_FIRST, 
IECODE_CO_LAST, 
IECODE_C1_FIRST, 
IECODE_C1_LAST, 
IECODE_COMM_CODE_FIRST, 
IECODE_COMM_CODE_LAST, 
IECODE_KEY_CODE_FIRST, 
IECODE_KEY_CODE_LAST, 
IECODE_LATIN1_FIRST, 
IECODE_LATIN1_LAST, 
IECODE_LBUTTON, 
IECODE_MBUTTON, 
IECODE_NEWACTIVE, 
IECODE_NOBUTTON, 
IECODE_RBUTTON, 
IECODE_REQCLEAR, 
IECODE_REQSET, 
IECODE_UP_PREFIX, 
IECODEB_UP_PREFIX, 
IEQUALIFIER_CAPSLOCK, 
IEQUALIFIER_CONTROL, 
IEQUALIFIER_INTERRUPT, 
IEQUALIFIER_LALT, 
IEQUALIFIER_LBUTTON, 
IEQUALIFIER_LCOMMAND, 
IEQUALIFIER_LSHIET, 
IEQUALIFIER_MBUTTON, 
IEQUALIFIER_MULTI BROADCAST, 
IEQUALIFIER_NUMERICPAD, 
IEQUALIFIER_RALT, 
IEQUALIFIER_RBUTTON, 
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IEQUALIEFIER_RCOMMAND , 
IEQUALIFIER_RELATIVEMOUSE, 
IEQUALIFIER_REPEAT, 
IEQUALIFIER_RSHIFT, 
IEQUALIFIERB_CAPSLOCK, 
IEQUALIFIERB_CONTROL, 
IEQUALIFIERB_INTERRUPT, 
IEQUALIFIERB_LALT, 
IEQUALIFIERB_LBUTTON, 
IEQUALIFIERB_LCOMMAND, 
TEQUALIFIERB_LSHIFT, 
IEQUALIFIERB_MBUTTON, 
IEQUALIFIERB_MULTI BROADCAST, 
IEQUALIFIERB_NUMERICPAD, 
IEQUALIFIERB_RALT, 
IEQUALIFIERB_RBUTTON, 
IEQUALIFIERB_RCOMMAND 
IEQUALIFIERB_RELATIVEMOUSE , 
IEQUALIFIERB_REPEAT, 
IEQUALIFIERB_RSHIET, 


ig_Height, 
“tere eData, 
g_Le ftEdge, 
ear enenen ge 
ig_PlaneOnOff, 
g_PlanePick, 
ig_SIZEOF, 
ig_TopEdge, 

i idth, 
gnored, 
im_Class, 
im_Code, 
im_ExecMessage, 
im_IAddress, 
im_IDCMPWindovw, 


im_MouseY, 
im_Quali fier, 
im_Seconds, 
im_SIZEOEF, 
im_SpecialLink, 
image, 
IMAGE_NEGATIVE, 
IMAGE_POSITIVE, 
imagery, 
INACTIVEWINDOW, 
IND_ADDHANDLER, 
IND_REMHANDLER, 
IND_SETMPORT, 
IND_SETMTRIG, 
IND_SETMTYPE, 
IND_SETPERIOD, 
IND_SETTHRESH, 


25-142 
25-140 
25-141 
25-53 
25-41 
25-51 
25-49 
25-27 
25-33 
25-35 
25-55 
25-58 
25-39 
25-47 
25-21 
25-29 
25-23 
25-25 
25-45 
25-37 
25-43 
25-31 
25-74 
25-72 
25-73 
25-70 
25-71 
25-75 
25-76 
25-66 
25-67 
25-64 
25-65 
25-77 
25-78 
25-81 
25-83 
25-87 
25-84 
25-82 
25-94 
25-92 
25-62 
25-63 
25-102 
25-104 
25-118 
25-106 
25-122 
25-110 
25-98 
25-126 
25-120 
25-114 
25-108 
25-124 


25-112 
25-128 
25-116 
25-100 
25-103 
25-105 
25-119 
25-107 
25-123 
25-111 
25-99 

25-127 
25-121 
25-115 
25-109 
25-125 
25-113 
25-129 
25-117 
25-101 
37-89 

27-769 
27-768 
27-770 
27-763 
27-830 
27-823 
27-822 


27-833, 48-60, 48-61 


27-765 
27-767 
27-349 
27-855 
27-859 
27-846 
27-868 
27-888 
27-883 
27-876 
27-877 
27-863 
27-882 
27-893 
27-891 
27-175, 
27-1610 
27-1609 
27-256, 
27-934 
24-19 
24-20 
24-24 
24-26 
24-25 
24-23 
24-22 


27-253, 


27-272, 


27-363, 27-761, 


27-363, 27-782 
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27-778, 


27-828 
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IND_WRITEEVENT, 
Info, 
InfoData, 
InitAnimate, 
initialize, 
inner -Window, 
Input, 
roca 
INREQUEST, 
INTB_AUDO, 
INTB_AUD1, 
INTB_AUD2, 
INTB_AUD3, 
INTB_BLIT, 
INTB_COPER, 
INTB_DSKBLK, 
INTB_DSKSYNC, 
INTB_EXTER, 
INTB_INTEN, 
INTB_PORTS, 
INTB_RBE, 
INTB_SETCLR, 
INTB_SOETINT, 
INTB_TBE, 
INTB_VERTB, 
integer, 
intena, 
intenar, 
INTERLACE, 
Peon ape: 
INTE_AUDO, 
INTF_AUD1, 
INTF_AUD2, 
INTE_AUD3, 
INTE_BLIT, 
INTE_COPER, 
INTE_DSKBLK, 
INTE_DSKSYNC, 
INTE_EXTER, 
INTE_INTEN, 
INTE_PORTS, 
INTE_RBE, 
INTE_SETCLR, 
INTE_SOETINT, 
INTE_TBE, 
INTE_VERTB, 
intreq, 
intreqr, 
meets 
Intuit, 
IntuiText, 
INTUITICKS, 
IntuitionBase, 
Lo_Actual, 
IO_BAUD, 
IO_BRKTIME, 


24-21 
17-32 
16-94 
20-49 
27-1259 
27-1095 
17-22 
25-133, 
27-1154 
26 - 26 
26-25 
26-24 
26-23 
26-27 
26-29 
26-32 
26-21 
26-20 
26-19 
26-30 
26-22 
26-16 
26-31 
26-33 
26-28 
27-637 
11-85 
11-34 
14-24 
12-33, 22-16 
26-45 
26-44 
26-43 
26-42 
26-46 
26-48 
26-51 
26-40 
26-39 
26-38 
26-49 
26-41 
26-37 
26-50 
26-52 
26-47 
11-86 
11-35 
27-844 
27-349 
27-670 
27-938 
28-46, 
8-48 
40-117 
40-118 


27-61 


28-53 
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io_ClipID, 


io_Data, 
io_DestCols, 
io_DestRovws, 
1o_Device, 
io_Error, 
IO_EXTELAGS, 
io_Flags, 
io_Length, 
io_Message, 
io_Modes, 
io_Offset, 
IO_PARFLAGS, 
io_Parm0, 
io_Parnl, 
io_Parn2, 
io_Parn3, 
IO_PARSTATUS, 
IO_PEXTELAGS, 
io_PrtCommand, 
IO_PTERMARRAY, 
io_RastPort, 
IO_RBUELEN, 


1o_SrcHeight, 
1o_SrcWidth, 
io_Srcx, 
io_Srcy, 
IO_STATUS, 
IO_STOPBITS, 
IO_TERMARRAY, 
io_Unit, 
IO_WRITELEN, 
ioa_AllocKey, 
ioa_Cycles, 
ioa_Data, 
ioa_Len P 
jioa_Period, 
ioa_SIZEOE, 
ioa_Volune, 
ioa_WriteMsg, 
IOAudio, 


Locr_SIZEOE. 


iodrpr_SIZEOE, 

IODRPReq, 

IoErr, 

IOEXTPAR, 

IOEXTPar_SIZE, 
IOEXTPar_SIZE-IOEXTSER_SIZE, 


2-44, 36-129, 
36-147 
36-144 
36-143 
36-141 
36-142 
40-124 
40-122 
40-119 

8-44 

40-121 

2-45 

2-50 

2-46 

2-47 

2-48 

2-52 

2-49 

2-51 

2-44 

8-41 

8-53 

36-148 
36-137 

17-35 

34-95 
34-123, 37-90, 
37-89, 37-94 


36-137, 44-36 


37-91 
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IOEXTSER, 
IOEXTSER_SIZE, 
IOEXTTD, 
IOPAR, 
Lopcr_SIZEOF, 
IOPrtCadReq, 
IOP?” 

IORO, 

IOR1, 

IOSER, 

IOST, 
IOSTD_SIZE, 
IOTD_COUNT, 
IOTD_SECLABEL, 
IOTD_SIZE, 
IOTV_SIZE, 
IOTV_TIME, 
IS_SIZE, 


ISDRAWN, 
ISGRTRX, 
ISGRTRY, 
IsInteractive, 
ISLESSX, 
ISLESSY, 

Lt; 
it_BackPen, 
it_DrawMode, 
it_FrontPen, 
it_I Text, 
it_ITextFont, 
it_KludgeFill00, 
it_LeftEdge, 
it_NextText, 
it_SIZEOE, 
it_TopEdge, 
ITALIC, 

iten, 

I TEMENABLED, 
items, 
ITEMTEXT, 
IText, 

its, 

IV_SIZE, 
joyOdat, 
joyldat, 
Joys’: 


KBD_ADDRESETHANDLER, 
KBD_READEVENT, 
KBD_READMATRIX, 
KBD_REMRESETHANDLER, 
KBD_RESETHANDLERDONE , 
KC_NOQUAL, 
KC_VANILLA, 
KCB_CONTROL, 
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ICK, 
km_HiCapsable, 
km_HikKeyMap, 


km_HiRepeatable, 
sable, 
km_LoKeyMap, 
km_LoKeyMap 8, 
kan_LoRepeatable, 
kon_SIZEOF, 
KNOBHIT, 
KNOBHMIN, 
KNOBVMIN, 

Layer, 
Layer_Info, 
LayerInfo, 
LayerInfo_extra, 
layers, 

leaves, 

left, 

LEEFTBORDER, 
LeftTop, 

LETTER, 
li_broadcast, 

li ereserved, 
i_check_lp, 
li_LayerInfo_extra, 
li_Lock, 
1i_Locker, 
li_locknest, 
li_LockPort, 
li_longreserved, 
li_obs, 

li_pad, 
1i4_RP_ReplyPort, 
1i_SIZEOF, 
li_top_layer, 
li_wordreserved, 
LIB_BASE, 
LIB_SIZE, 
LIBINIT, 

library, 
lie_blitbuff, 
lie_env, 
lie_FreeClipRects, 
lie_men, 


40-91 
37-95, 
45-105 
34-74, 
36-135 
36-129 
34-77, 
37-76 
37-77 
40-71, 
40-74, 
33-58, 
45-106 
45-107 
45-108 
37-99, 44-38 

44-37 

6-23, 12-48, 12-49, 12-50, 
12-65, 22-30, 22-31, 22-32 
27-183 

7-68 

7-69 

17-49 

7-66 

7-67 

27-337, 27-389, 27-1724 
27-674 

27-676 

27-672 

27-706 

27-704 

27-696 

27-699 

27-708 

27-711 

27-701 

43-20 

27-115, 27-158, 27-165 
27-166 

27-120 

27-157 

27-1732 

27-1157 

6-24, 6-25, 6-26, 6-27, 6-28 
11-24 
11-25 
11-47 
4-48, 
29-21 
29-19 
29-20 
29-22 
29-23 
30-28 
30-29 
30-32 


37-96, 40-142 


34-75, 34-76 


34-78, 34-79, 34-80 


40-72, 
40-75, 
34-95, 


40-73 
40-76, 
40-91, 


40-77, 40-78 
45-105 


12-63, 12-64, 


4-48, 16-116, 16-116 


30-34 
30-25 
30-37 
30-31 
30-33 
30-35 
30-26 
30-30 
30-38 
30-13 
4-43 
30-20 
30-19 
30-18 
30-21 
30-16 
30-15 
30-14 
30-17 
30-22 
27-590 
27-593 
27-594 
7-15 
31-32 
27-1357 
31-16 
27-41 
27-337 
27-380 
27-451 
27-741 
27-1602 
31-39 
31-43 
31-34 
31-46 
31-38 
31-42 
31-40 
31-37 
31-45 
31-35 
31-41 
31-36 
27-1356, 31-47 
31-33 
31-44 
12-105, 32-48 
6-18, 12-55, 18-150, 
12-105, 32-48 
16-16, 23-31 
31-20 
31-17 
31-19 
31-18 


22-19, 28-48, 32-44, 37-47 
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lie_SIZEOEF, 
like, 
LINEMODE, 
list, 
listing, 


LMN_REGION, 
LN_PRI, 
LoadSeg, 
location, 

Lock, 
LONELYMESSAGE, 
LONGINT, 
LOWCHECKWIDTH, 
LOWCOMMWI1 DTH, 
lr__cliprects, 
r_pl, 

lr_Back, 
lr_ClipRect, 
fcr, 

lr_cr2, 
lr_crnew, 
lr_DamageList, 
lr_Flags, 
lr_Front, 
lr_l1_LockMessage, 
lr_LayerInfo, 
lr_LayerLockCount, 
lr_LayerLocker, 
lr_Lock, 
lr_LockCount, 
lr_LockMessage, 
lr_LockPort, 
lr_MaxX, 
lr_MaxyY, 
lr_Minx, 
l[r_MinyY, 
lr_RastPort, 
lr_ReplyPort, 
lr_reserved, 
lr_reservedl, 
lr_Scroll_X, 
lr_Scroll_y, 
lr_SIZEOE, 
lr_SuperBitMap, 
lr_SuperClipRect, 
lr_SuperSaverClipRects, 
lr_Window, 
M_ASM, 

M_AWM, 

M_LNM, 


31-21 
27-866 
3-67 

27-217 
27-53, 
27-318, 27-372, 27-425, 
27-584, 27-638, 27-691, 
27-851, 27-905, 27-959, 
27-1118, 27-1171, 


27-106, 27-159, 27-212, 
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File numbers for cross-reference listing: 


:adkbits .h 
:cia.h 
:console.h 
:custom.h 
:display.h 
:error.h 

fx.h 
:icon.n 
:intuinternal .h 
:keyboard.h 


:audio.h 
:clip.h 
:conunit .h 
:dec.h 
:dmabits .h 
:fcntl.h 
goes 
:input.h 


:intuition. 


3 

7 
11 
15: 
19 
23: 
27: 
31: 
35: 
39: 


h 


:blit.h 
:Cclipboard.h 


eee 
bk 
:dos.h 


:bootblock.h 
:collide.h 
:ctype.h 
:diskfont.h 
:dosextens .h 
:gels.h 
:graphint.h 
:intbits.h 
siosl.h 
:limits.h 


dis 


gameport.h 
fomacros.h 
nputevent .h 
intuitionbase.h 
layers.h 


eee 
:macros.h :math. 
:narrator .h 
:prtbase.h 
:sprite.h 
:timer .h 


:workbench .h 


:startup.h 
:trackdisk 


A_OR_B, 


ac_pad, 

ac_per, 

ac_ptr, 

ac_vol, 

aCAM, 

ACCESS_READ, 
ACCESS_WRITE, 

acos, 
ACTION_COPY_DIR, 
ACTION_CREATE_DIR, 
ACTION_CURRENT_VOLUME , 
ACTION_DELETE_OBJECT, 
ACTION_DIE, 
ACTION_DISK_CHANGE , 
ACTION_DISK_INEO, 
ACTION_DISK_TYPE, 
ACTION_EVENT, 
ACTION_EXAMINE_NEXT, 
ACTION_EXAMINE_OBJECT, 
ACTION_FREE_LOCK, 
ACTION_GET_BLOCK, 
ACTION_INEO, 
ACTION_INHIBIT, 
ACTION_LOCATE_OBJECT, 
ACTION_NIL, 
ACTION_PARENT, 
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ACTION_READ, 
ACTION_RENAME_DISK, 
ACTION_RENAME_OBJECT, 
ACTION_SET_COMMENT, 
ACTION_SET_MAP, 
ACTION_SET_PROTECT, 
ACTION_TIMER, 
ACTION_WAIT_CHAR, 
ACTION_WRITE, 
ACTIVATE, 
Activation, 
ActiveGadget, 
ete 
ActivePInfo, 
ActiveScreen, 
ActiveWindow, 
ActiView, 
ADALLOC_MAXPREC, 
ADALLOC_MINPREC, 


ADCMD_SETPREC, 
ADCMD_WAITCYCLE, 
ADCMDB_NOUNIT, 
ADCMDE_NOUNIT, 
AddFreeList, 

aDEN1, 

aDEN2, 

aDEN3, 

aDEN4, 

aDENS, 

aDEN6, 
ADHARD_CHANNELS, 
ADIOB_NOWAIT, 
ADIOB_PERVOL, 
ADIOB_SYNCCYCLE, 
ADIOB_WRITEMESSAGE, 
ADIOERR_ALLOCEAI LED, 
ADIOERR_CHANNELSTOLEN, 
ADIOERR_NOALLOCATION, 
ADIOF_NOWAIT, 
ADIOF_PERVOL, 
ADIOF_SYNCCYCLE, 
ADIOF_WRITEMESSAGE, 
ADKB_FAST, 
ADKB_MEMPREC, 
ADKB_MSBSYNC, 
ADKB_PRECOMP0, 
ADKB_PRECOMP1, 
ADKB_SETCLR, 
ADKB_UARTBRK, 
ADKB_USEOP1, 
ADKB_USEOV1, 


:parallel.n 
:rastport.h 


A43:mathffp.h 
47:potgo. 
51:regions.h 
55:stdio.h 


h 59:translator.h 


:misc.h 


:text .h 
‘view.h 


3-34 

3-35 

3-37 

3-36 

3-24, 3-34, 3-35, 3-37 
48-108 
3-25, 3-34, 3-35, 3-36, 
41-6, 43-31, 55-65 
13-91 

13-88 

13-92 

13-89 

13-87 

13-90 
48-111 
19-57 

19-60 

42-8, 42-94 
20-128 
20-131 
20-119 
20-125 
20-117 
20-142 
20-134 
20-141 
20-118 
20-133 
20-132 
20-124 
20-115 
20-135 
20-140 
20-120 
20-114 
20-138 


3-37 


20-123 
20-121 
20-126 
20-137 
20-116 
20-130 
20-139 
20-129 
20-122 
34-1287 
34-299 
33-123 
33-125 
33-124 
33-79, 35-45 
33-78, 34-1005, 35-44 
26-27 
2-17 
2-16 
2-27 
2-21 
2-19 
2-23 
2-22 
2-20 
2-24 
2-25 
2-26, 2-27 
29-40 
48-66 
48-65 
48-64 
48-63 
48-62 
48-61 
2-14 
2-33 
2-29 
2-31 
2-35 
2-39 
2-40 
2-38 
2-34 
2-30 
2-32 
2-36 
1-21 
1-17 
1-20 
1-16 
Lo 
1-14 
1-18 
1-25 
1-29 


:printer.h 
:serial.h 
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ADKB_USE1P2, 
ADKB_USE1V2, 
ADKB_USE 2P3, 
ADKB_USE 2V3, 
ADKB_USE3PN, 
ADKB_USE3VN, 
ADKB_WORDSYNC, 
adkcon, 
adkconr, 
ADKE_FAST, 
ADKF_MEMPREC, 
ADKE_MSBSYNC, 
ADKE_PREOOONS, 
ADKF_PRE140NS, 
ADKF_PRE280NS, 
ADKF_PRES60NS, 
ADKF_PRECOMP0, 
ADKF_PRECOMP1, 
ADKE_SETCLR, 


ADKF_USEOV1, 
ADKF_USE1P2, 
ADKF_USE1V2, 
ADKF_USE 2P3, 
ADKF_USE2V3, 
ADKF_USE3PN, 
ADKF_USE3VN, 
ADKF_WORDSYNC, 
aEXTEND, 


AFE_MEMORY, 
aFNTO, 
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aJFY3, 

aJFYS, 

aJFY6, 

aJEY7, 
ALERT_COUNTDOWN, 
ALERT_TYPE, 
ALERTLAYERSNOMEM, 
AlgoStyle, 
AllocWBObject, 
aLMS, 


AMIGARIGHT, 
AN_Intuition, 
ANEC, 

ANBNC, 

aNEL, 
ANERACSIZE, 
AnimBob, 
AnimComp, 


AnimCRoutine, 
ANIMHALE , 
animKey, 
AnimOb, 
AnimORoutine, 
AnO1dX, 
AnOldY, 

AnX, 

Any, 
AO_GraphicsLib, 
AO_LayersLib, 
AOlPen, 
apattern, 

en, 

aPERE, 
aPERFO, 

aPLD, 

aPLU, 
APointer, 
aPROPO, 
aPROP1, 

aPROP 2, 
APtrHeight, 
APtrWidth, 
ArealInfo, 
AREAOUTLINE, 
AreaPtrn, 
AreaPtSz, 
argl, 

arg2, 


1-24 
1-28 
1-23 
1-27 
1-22 
1-26 
1-19 
13-85 
13-29 
1-38 
1-34 
aor 
1-48 
1-49 
1-50 
1-51 
1-33, 
1-32, 
i~31 
1-35 
1-42 
1-46 
1-41 
1-45 
1-40 
1-44 
1-39 
1-43 
1-36 
48-121 
16-67 
16-66 
16-62 
16-60 
16-63 
16-61 
16-71 
48-76 
48-77 
48-86 
48-78 
48-79 
48-80 
48-81 
48-82 
48-83 
48-84 
48-85 
43-44 
24-160 
33-386, 33-387 
25-18, 25-19 
48-113 

48-39 

48-95 

48-97 


1-49, 1-51 
1-50, 1-51 


48-96 

48-92 

48-94 

48-93 

33-382 

34-1889 

39-43 

50-75 

29-38 

48-105 

34-1791 

34-493, 34-716 
34-1923 

34-1924 

33-144 

34-1927 

34-1925, 34-1927 
34-1926, 34-1927 
33-386, 33-387 


3-26, 3-34, 3-35, 3-37 

3-27, 3-34, 3-35, 3-36, 3-37 
48-40 

24-47 

24-203 

24-164, 24-171, 24-189, 24-190, 


24-194, 24-228 
24-196 

24-48 

24-253, 24-253 
24-201, 24-206, 
24-225 
24-214 
24-214 
24-217 
24-217 
33-386 
33-387 
27-28, 
33-146 
33-236 
48-102 
48-103 
48-74 

48-73 

33-99 

48-90 

48-89 

48-88 

33-101 
33-102 
50-18, 
27-28, 
27-31, 
27-31, 
42-38 

42-38 


24-209 


50-63 


50-58, 50-58 
27-33, 50-101 
50-56 
50-65 


24-193, 
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aRI, 
aRIN, 
aRIS, 


aSBC, 
aSEC, 


aSGR22, 
aSGR23, 
aSGR24, 
aSGR3, 
aSGR4, 
ASHIFTSHIET, 
aSHORP0O, 
aSHORP1, 
aSHORP 2, 
aSHORP 3, 
aSHORP4, 
aSHORPS, 
aSHORP6, 
asin, 

aSLPP, 
aSLRM, 
ASPECT_HORIZ, 
ASPECT_VERT, 
aSTBM, 
aSuSsoO, 
aSUS1, 
aSUS2, 
aSUS3, 


aTSsS, 

aud, 
AudChannel, 
audio, 
AUDIONAME , 
AUL 


AUserExt, 
AUserStuff, 
AUTOBACKPEN, 
AUTODRAWMODE , 
AUTOFRONTPEN, 
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AUTOITEXTFONT, 
AUTOKNOB, 
AUTOLEETEDGE, 
AUTONEXTTEXT, 
AUTOTOPEDGE, 
AvailFonts, 
AvailFontsHeader, 
aVERPO, 
aVERP1, 
aVTS, 

AXOf fset, 
AYOffset, 
B2BOBBER, 
B2NORM, 
B2SWAP, 
back, 
BACKDROP, 
BackFill, 
BackPen, 
BACKSAVED, 
BADDR, 
BADGADGET, 
BADMESSAGE, 
BADSTATE, 
BarHBorder, 
BarHeight, 
BarLayer, 
BarVBorder, 
BAUD_110, 
BAUD_1200, 
BAUD_19200, 
BAUD_2400, 
BAUD_300, 
BAUD_4800, 
BAUD_9600, 
BAUD_MIDI, 
BaudRate, 
bb_chksun, 
bb_dosblock, 
bb_id, 
BBID_DOS, 
BBID_KICK, 
BBNAME_DOS, 
BBNAME_KICK, 
BCOB_DEST, 
BCOB_SRCA, 
BCOB_SRCB, 
BCOB_SRCC, 
BCOF_DEST, 
BCOF_SRCA, 
BCOE_SRCB, 
BCOF_SRCC, 
BCIF_DESC, 
BDRAWN, 
beamsync, 
BeatX, 


46-41 
48-38 


48-69 
48-68 
48-71 
48-70 


33-386, 33-387 
42-10, 42-95 


42-95 
48-115 
48-117 
48-116 
48-118 
48-119 
48-120 
48-107 
42-92 
42-90 
42-91 
48-91 
13-93 
13-86 
2-12 
2-12 
3-70 
24- 230 


24-66, 24-67, 


34-1905 
34-1906 
34-1904 


34-1909 
34-629 
34-1907 
34-1910 
34-1908 
16-65 
16-70 
48-99 
48-100 
48-114 
33-104 
33-104 
24- 261 
24-259 
24-260 
6-27 
34-1271 
34-229 
34-738, 
24-28 
19-119 
33-389 


34-787 


34-1468 


34-1468 


24-230 
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Beaty, 
BEEPING, 
Before, 
BgPen, 
BITCLR, 
BitMap, 


BITSET, 
BITSPERBYTE, 
BITSPERLONG, 

BlitLock, 
BLITMSG_FAULT, 
BlitNest, 
BlitOwmer, 
BLITREVERSE, 
blitsize, 
blitter, 
BlitWaitQ, 
blockpen, 
blitadat, 
blitafwn, 
bltalwn, 
bitamod, 
blitapt, 
bltbdat, 
bltbmod, 
bltbpt, 
bltcdat, 
bltcmod, 
bltcono, 
bltconl, 
bltcpt, 
blitddat, 
bltdmod, 
bltdpt, 
blithd, 
bltnode, 
bitsize, 
bltsarv, 
blittl, 
BNDRYOFE, 
Bob, 
BobConmp, 
BOBISCOMP, 
BOBNIX, 
BOBSAWAY, 
BOBUPDATE, 
BobVSprite, 
BOOLGADGET, 
BootBlock, 
BOOTSECTS, 
Border, 
BorderBotton, 
BORDERHIT, 
BorderLeft, 
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BORDERLESS, 
BorderLine, 
BorderRight, 
BorderRPort, 
BorderTop, 
BOTTOMBORDER, 
BOTTOMHIT, 
bottommost, 
bounds, 
bpattern, 
BPen, 
bplimod, 

bp1 2mod, 
bplcond, 
bpliconl, 
Pecos: 
ldat, 

plpt, 
broadcast, 
BROTHER_15XL, 
bsblthd, 
bsblttl, 
BSHIFTSHIET, 
Bu fBu f fer, 
Buf fer, 

Buf ferPos, 
Bu fPath, 
BUFSIZ, 

Bu fX, 

BufY, 
BUserExt, 
BUSERELAGS, 
BUserStuff, 
BWAITING, 
ereserved, 
ESPERLONG, 
BytesPerRow, 
Carg, 
CBD_CURRENTREADID, 
CBD_CURRENTWRITEID, 
CBD_POST, 
CBERR_OBSOLETEID, 
CBM_MPS1000, 
CBump, 

ccode, 
CD_ASKKEYMAP, 
CD_SETKEYMAP, 
ceil, 

CEND, 

ch_masks, 
channmask, 

check_Ilp, 

CHECKED, 

CheckI mage, 
CHECKIT, 
CheckMark, 


B 


34-87 
34-1534 
24-159 
50-62 
25-16, 
6-39, 6 
34-245, 
34-1587 


25-15, 27-20, 


19-44 
19-46 
26-48 
26-63 
26-49 
26-52 
3-66 
3-87 
26-30 
26-51 
33-139, 
13-69 
13-54 
13-55 
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33-211, 34-78, 34-122, 34-225, 34-296, 
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50-22 
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16-34 
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56-30 

56-38 
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FPF_DISKFONT, 
FPEF_PROPORTIONAL, 
FPE_REMOVED, 
FPF_REVPATH, 
EPF_ROMEONT, 
FPF_TALLDOT, 
EPE_WIDEDOT, 
EFPHALE , 
FPONE, 

EPTEN, 
FPZERO, 
FreeFreeList, 
FREEHORIZ, 
FreeList, 
FREEVERT, 
FreewBObject, 
freopen, 
frexp, 

front, 
FrontPen, 
EFRST_DOT, 
ES_NORMAL, 
ESB_BOLD, 
FSB_EXTENDED, 
ESB_ITALIC, 
FSB_UNDERLINED, 
fseek, 
FSE_BOLD, 
ESE_EXTENDED, 
FSF_ITALIC, 
FSE_UNDERLINED, 
ftell, 
function, 
GADGBACKFILL, 
GADGDISABLED, 
Gadget, 


GADGET0002, 
GADGETCOUNT, 
GADGETDOWN , 
Gadget ID, 
ETON, 
GadgetRender, 
GadgetReturn, 
Gadgets, 
GadgetText, 


aRRDGESUE- 


GADGHBOX, 


56-31 

56-39 

56-43 

56-33 

56-29 

56-35 

56-37 

43-20 

43-19 

43-18 

43-21 

29-40 

34-631 

61-88, 61-126 

34-633 

29-40 

55-61 

42-93 
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34-738, 34-787 
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56-17 

56-22 
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56-20 

56-24 

55-56 

56-23 

56-19 

56-21 

56-25 

55-62 
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34-417 

33-123, 33-143, 34-220, 34-286, 34-288, 
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61-124 
34-527 
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34-979 
34-354 
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34-323 
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34-369 
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34-366 
34-371 
34-377 
34-383 


33-143 


34-506 
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GADGIMMEDIATE, 
GamePortTrigger, 
GELGONE, 
gelHead, 
GelsiInfo, 
gelTail, 

GENLOC, 
GENLOCK_AUDIO, 
GENLOCK_VIDEO, 
getc, 

Rocco 

tIcon, 
GetWBObject, 
GfxBase, 
GID_DOWNSCROLL, 
GID_HORIZSCROLL, 
GID_LEFTSCROLL, 
GID_NAME , 
GID_RIGHTSCROLL, 
GID_UPSCROLL, 
GID_VERTSCROLL, 
GID_WBOBJECT, 
GIMMEZEROZERO, 
GOODI TEMDRAWN , 
GOODSUBDRAWN, 
GPCT_ABSJOYSTICK, 
GPCT_ALLOCATED, 
GPCT_MOUSE, 
GPCT_NOCONTROLLER, 
GPCT_RELJOYSTICK, 
GPD_ASKCTYPE, 
GPD_ASKTRIGGER, 
GPD_READEVENT, 
GPD_SETCTYPE, 
GPD_SETTRIGGER, 
GPDERR_SETCTYPE, 


Spr aheys- 
gpt_Timeout, 
gpt_XDelta, 


graphics, 


GRAPHICS_CLIP_H, 
GRAPHICS_COLLIDE_H, 
GRAPHICS_COPPER_H, 
GRAPHICS_GELS_H, 
GRAPHICS_GFX_H, 
GRAPHICS_GFXBASE_H, 
GRAPHICS_GFXMACROS_H, 
GRAPHICS_GRAPHINT_H, 
GRAPHICS_LAYERS_H, 
GRAPHICS_RASTPORT_H, 
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GRAPHICS_REGIONS_H, 
GRAPHICS_SPRITE_H, 
GRAPHICS_TEXT_H, 
GRAPHICS_VIEW_H, 
GRELBOTTOM, 
GRELHEIGHT, 
GRELRIGHT, 
GRELWIDTH, 
GRET_REQSELECT, 
GRET_REQUEST, 
GRET_RJM, 
GRET_RJMSELECT, 
GZZGADGET, 
GZZHeight, 
GZZMouseX, 
GZZMouseY, 
GZZWidth, 

HAM 


HARDWARE_ADKBITS_H, 
HARDWARE_BLIT_H, 
HARDWARE_CUSTOM_H, 
HARDWARE_DMABITS_H, 
HARDWARE_INTBITS_H, 
HeadConp, 

HeadOb, 

Height, 


HIGHBOX, 
HIGHCOMP, 
HIGHELAGS, 
HIGHIMAGE, 
HIGHITEM, 
HIGHNONE, 
HIRES, 
HIRESGADGET, 
HIRESPICK, 
HitMask, 
HitScreen, 
HoldMinYMouse, 
HOLDNMODIEY, 
HorizBody, 
HorizPot, 
HP_LASERJET, 
HP_LASERJET_PLUS, 
HPotRes, 
HSIZEBITS, 
HSIZEMASK, 
hthick, 
HUGE, 
HUGE_VAL, 
HWaitPos, 
Io, 


34-438 
23-28 
24-30 
50-42 
50-37, 
50-42 
26-60 
60-63 
60-64 
55-49, 
55-50 


50-59, 50-59 


55-50 
33-97, 33-97 
6 


61-157 

61-154 

61-155 

61-152 

61-150 

34-1277 

33-321 

33-322 

23-41 

23-36 

23-39 

23-37 

23-40 

23-15 

23-17 

23-14 

23-16 

23-18 

23-45 

23-29 

23-30 

23-31 

23-32 

23-23 

23-25 

23-24 

23-26 

6-5, 16-20, 27-17, 34-25, 34-29, 34-33 
34-37, 34-41, 34-45, 35-21, 50-5, 
6-1, 6-2, 34-28 
8-1, 8-2 

11-1, 11-2 

24-1, 24-2 

6-4, 25-1, 25-2, 
26-1, 26-2 

27-1, 27-2 

28-1, 28-2 

34-40, 39-5, 39-6 
27-16, 34-36, 50-1, 50-2 


34-24, 50-4, 51-4, 60-4 


51-1, 51-2 

53-1, 53-2 

16-19, 34-44, 56-1, 56-2 
34-32, 35-20, 60-1, 60-2 
34-393 

34-402 

34-395 

34-399 

33-337 

33-336 

33-335 

33-338 

34-512 

34-1225 

34-1218 

34-1219 

34-1224 

60-60 

1-11, 1-12, 1-53 

3-11, 3-12, 3-96 

13-11, 13-12, 13-114 
18-11, 18-12, 18-53 
32-12, 32-13, 32-53 
24-228 

24-201 

24-104, 33-136, 34-76, 34-120, 
34-293, 34-827, 34-1100, 
34-1555, 45-85, 53-13 
34-178 

34-176 

34-172 

34-174 

34-189 

34-180 

60-58 

33-54 

33-47 

24-109 

33-199 

33-195 

17-21 

34-612 

34-570 

34-1802 

34-1803 

34-621 

3-15 

3-17 

33-138 

42-75 

40-1 

11-35, 11-45, 11-45 
14-19 

14-19 

14-19 

42-72 


34-211, 
34-1339, 34-1452, 
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I_PID2, 
IAddress, 
IBase-, 


IBitMap, 
icon, 
ICONNAME, 
id_ esPerBlock, 
d_DiskState, 
aa tee 
ID_DOS_DISK, 
id_InUse, 
ID_KICKSTART_DISK, 
ID_NO_DISK_PRESENT, 
ID_NOT_REALLY_DOS, 
id_NumBlocks, 
id_NumB1locksUsed, 
id_NumSoftErrors, 
id_UnitNumber, 
ID_UNREADABLE_DISK, 
ID_VALIDATED, 
ID_VALIDATING, 
id_VolumeNode, 
ID_WRITE_PROTECTED, 


ie_addr, 

ie_Class, 

ie_Code, 
ie_EventAddress, 
ie_NextEvent, 
ie_position, 
ie_Qualifier, 
ie_SubClass, 
ie_TimeStanmp, 

ie_x, 

ie_xy. 

je_y, 
IECLASS_ACTIVEWINDOW, 
IECLASS_CLOSEWINDOW, 
IECLASS_DISKINSERTED, 
IECLASS_DISKREMOVED, 
IECLASS_EVENT, 


IECLASS_ INACTIVEWINDOW, 
IECLASS_MAX, 
IECLASS_MENULIST, 
IECLASS_NEWPREES, 

CLASS 


IE NULL , 
IECLASS_POINTERPOS, 


IECLASS_RAWKEY, 
IECLASS_RAWMOUSE, 


IECLASS_REFRESHWINDOW, 


IECLASS_REQUESTER, 


42-73 
34-935 


33-355, 33-356, 
33-362, 


33-360, 
33-366, 33-367 
33-114 
29-30 
29-30 
19-137 
19-132 
19-138 
19-157 
19-141 
19-164 
19-155 
19-158 
19-133 
19-135 
19-128 
19-130 
19-156 
19-151 
19-149 
19-139 
19-147 


34-1188, 34-1345 


34-956 
31-131, 
31-122 
31-124 
31-138 
31-121 
31-132, 
31-125 
31-123 
31-133 
31-128, 
31-130, 
31-129, 
31-53 
31-41 
31-51 
31-49 
31-27 
31-33 
31-35 
31-55 
10-76, 31-59 
31-39 

31-47 

31-21 

31-29 

31-23 

31-25 

31-45 

31-37 


31-138 
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TECLASS_SIZEWINDOW, 
IECLASS_TIMER, 
IECODE_ASCII_DEL, 
IECODE_ASCII_FIRST, 
IECODE_ASCII_LAST, 
IECODE_CO_FIRST, 
IECODE_CO_LAST, 
TECODE_C1_FIRST, 
IECODE_C1_LAST, 
IECODE_COMM_CODE_FIRST, 
IECODE_COMM_CODE_LAST, 
IECODE_KEY_CODE_FIRST, 
IECODE_KEY_CODE_LAST, 
IECODE_LATINI_FIRST, 
IECODE_LATIN1_LAST, 
IECODE_LBUTTON, 
IECODE_MBUTTON, 
IECODE_NEWACTIVE, 
IECODE_NOBUTTON, 
IECODE_RBUTTON, 
IECODE_REQCLEAR, 
IECODE_REQSET, 
IECODE_UP_PREFIX, 
IE UALIFIER_CAPSLOCK, 
IEQUALIFIER_CONTROL, 
IEQUALIFIER_INTERRUPT, 
IEQUALIFIER_LALT, 
IEQUALIFIER_LBUTTON, 
oe ALI FIER_LCOMMAND, 
EQUALIFIER_LSHIET, 
ALIFIER_MBUTTON, 
TEQUALIET MULTI BROADCAST, 
IEQUALIFIER_NUMERICPAD 
IEQUALIFIER_RALT, 
IEQUALIFIER_RBUTTON, 
IEQUALIFIER_RCOMMAND , 
IEQUALIEIER_RELATIVEMOUSE, 
ITEQUALIFIER_REPEAT, 
Sa a ade 
f, 
Image, 


IMAGE_NEGATIVE, 
IMAGE_POSITIVE, 
ImageBMap, 
ImageData, 
ImageShadow, 
INACTIVEWINDOW, 
IND_ADDHANDLER, 
IND_REMHANDLER, 
IND_SETMPORT, 
IND_SETMTRIG, 
IND_SETMTYPE, 
IND_SETPERIOD, 
IND_SETTHRESH, 
IND_WRITEEVENT, 


31-43 
31-31 
31-76 
31-74 
31-75 
31-72 
31-73 
31-77 
31-78 
31-68 
31-69 
31-66 
31-67 
31-79 
31-80 


31-83, 34-1915, 


31-85 
31-89 
31-86 


31-84, 34-1917, 


31-97 
31-95 


31-65, 34-1915, 


31-103, 33-327 
31-104 
31-111 
31-105, 
31-113 
31-107, 
31-101, 
31-115 
31-112 
31-109 
31-106, 
31-114 
31-108, 
31-116 
31-110 
31-102, 33-327 
36-31, 55-36 


33-327 


33-125, 33-144, 
34-1367, 61-56, 


34-1771 
34-1770 
34-245 
24-111, 34-828 


31-136, 


31-136, 
31-136, 
31-137, 


34-1923 
34-1925 


34-1924 
34-1926 


33-357, 
33-363, 


31-137, 


31-136 
31-137 
31-137 


34-1916 


34-1918 


34-1917 


34-819, 
61-57 


33-358, 33-359, 
33-364, 33-365, 


31-138 


34-895, 34-1203, 
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InfoData, 
INGADGETSTATE, 
InitAnimate, 
INMENUSTATE, 
innerHeight, 
innerWidth, 
inputevent, 
InputInterrupt, 
nputRequest, 
INREQUEST, 
INTB_AUDO, 
INTB_AUD1, 
INTB_AUD 2, 
INTB_AUD3, 
INTB_BLIT, 
INTB_COPER, 
INTB_DSKBLK, 
INTB_DSKSYNC, 
INTB_EXTER, 
INTB_INTEN, 
INTB_PORTS, 
INTB_RBE, 
INTB_SETCLR, 
INTB_SOFTINT, 


intenar, 
INTERLACE, 
Interrupt, 


INTE_AUDO, 

INTE_AUD1, 

INTF_AUD2, 

INTF_AUD3, 

INTF_BLIT, 

INTE_COPER, 
INTF_DSKBLK, 
INTE_DSKSYNC, 
INTE_EXTER, 
INTE_INTEN, 
INTE_PORTS, 

INTF_RBFE , 

INTF_SETCLR, 
INTF_SOEFTINT, 
INTE_TBE, 

INTF_VERTB, 

intreq, 

intreqr, 

IntuEvents, 
IntuiMessage, 
IntuiText, 

INTUITICKS, 
INTUITION_INTUINTERNAL_H, 
INTUITION_INTUITION_H, 
INTUI TION_INTUITIONBASE_H, 


19-127 
33-317 
24-253 
33-318 
33-140 
33-140 
10-24, 
33-118 
33-117 
34-1293 
32-25 
32-24 
32-23 
32-22 
32-26 
32-28 
32-31 
32-20 
32-19 
32-18 
32-29 
32-21 
32-15 
32-30 
32-32 
32-27 
13-83, 27-25, 27-26 
13-35 

17-22 


31-120, 


15-51, 15-52, 15-53, 15-65, 15-66, 15-67, 


26-35, 33-118 

32-44 

32-43 

32-42 

32-41 

32-45 

32-47 

32-50 

32-39 

32-38 

32-37 

32-48 

32-40 

32-36 

32-49 

32-51 

27-25, 27-26, 32-46 
13-84 

13-36 

33-121 

33-198, 34-913, 
34-224, 34-323, 
34-1012 

33-2, 33-3 
34-4, 34-5, 49-43, 61-30, 
33-18, 34-20, 35-1, 35-2 


34-959, 34-1191 
34-736, 34-754 


61-32 


Apr 29 10:15 1986 h.xref Page 26 


IntuitionBase, 
INVERSVID, 
io_Actual, 

io_Baud, 
io_BrkTime, 
io_ClipID, 
io_ColorMap, 
io_Command, 
i1o_CtlChar, 
io_Data, 
io_DestCols, 
io_DestRows, 
1o_Device, 
io_Error, 
io_ExtFlags, 
io_Flags, 
io_Length, 
io_Message, 
io_Modes, 
io_Offset, 
io_ParFlags, 
io_Parm0, 
io_Parnl, 
io_Parn2, 
io_Parn3, 
io_PExtFlags, 
1o_PrtCommand, 
io_PTermArray, 
io_RastPort, 
io_RBu fLen, 
io_ReadLen, 
io_SerFlags, 
io_Special, 
io_SrcHeight, 
1o_SrcWidth, 
io_Srcex, 
io_SrcyY, 
io_Status, 
io_StopBits, 
io_Ter ray, 
io_Unit, 
io_WriteLen, 
ioa_AllocKey, 
ioa_Cycles, 
ioa_Data, 
ioa_Len a 
ioa_Period, 
ioa_Request, 
ioa_Volume, 
ioa_WriteMsg, 
IOAudio, 
IO0C1lipReq, 
IODRPReq, 
IOExcess, 
IOExtPar, 
IOExtSer, 


33-67, 34-21, 35-38 
50-91 

7-44 

52-65 

52-66 

7-48 

48-145 

7-41, 48-127, 48-141 
52-62 
7-46 
48-151 
48-152 
7-39, 
7-43, 
52-64 
7-42, 
7-45 
7-38, 48-124, 
48-146 


7-47 
46-60 
48-131 
48-132 
48-133 
48-134 
46-58 
48-130 
46-61 
48-144 
52-63 
52-68 
52-71 
48-153 
48-150 
48-149 
48-147 
48-148 
46-59, 52-72 

52-70 

52-67 

7-40, 48-126, 48-140 
52-69 
2-44 
2-49 
2-45 
2-46 
2-47 
2-43 
2-48 
2-50 
2-42 
7-37 
48-137 
33-193 
46-35, 
49-71, 


48-125, 
48-129, 


48-139 
48-143 
48-128, 48-142 


48-138 


49-70, 49-76 
49-77, 52-35 


D - 97 


31-121, 33-121, 34-61 
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IOExtTD, 

IOPar, 
IOPARB_ABORT, 
IOPARB_ACTIVE, 
IOPARB_QUEUED, 
IOPARF_ABORT, 
IOPARF_ACTIVE, 
IOPARF_QUEUED, 
IOPArray, 

ae Eoeat 
IOPTB_PAPEROUT, 
IOPTB_PBUSY, 
IOPTB_PSEL, 
IOPTB_RWDIR, 
IOPTE_PAPEROUT, 
IOPTE_PBUSY, 
IOPTE_PSEL, 
IOPTF_RWDIR, 
IORequest, 
IOSERB_ABORT, 
IOSERB_ACTIVE, 
IOSERB_BUFRREAD, 
IOSERB_QUEUED, 
IOSERF_ABORT, 
IOSERF_ACTIVE, 
IOSERF_BUFRREAD, 
IOSERF_QUEUED, 
IOSTB_O UN, 
IOSTB_READBREAK, 
IOSTB_WROTEBREAK, 
IOSTB_XOFFREAD, 
IOSTB_XOFFWRITE, 
IOStdReq, 
IOSTF_OVERRUN, 
IOSTE_READBREAK, 
IOSTF_WROTEBREAK, 
IOSTE_XOFFREAD, 
IOSTF_XOFEWRITE, 
IOTArray, 
iotd_Count, 
iotd Req, 
iotd_SecLabel, 
IPointer, 
IPOINTHEIGHT, 
IPOINTHOTX, 
IPOINTHOTY, 
Iptr, 
IPtrHeight, 
IPtrWidth, 
iqd_FNKUHDPort, 
is_Node, 
isalnun, 
isalpha, 
isascii, 
iscntrl, 

iscsyn, 
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iscsynf, 
isdigit, 
ISDRAWN, 
isgraph, 
SCR X, 
ISGRTRY, 
ISLESSX, 
ISLESSY, 
islower, 
isprint, 
ispunct, 
Isrvstr, 
isspace, 
isupper, 
isxdigit, 
ItemCRect, 
ITEMDRAWN, 
ITEMENABLED, 
ItemFill, 
ITEMNUM, 
ITEMTEXT, 
IText, 
ITextFont, 
itof, 
IXOffset, 
TYyoOffset, 
JAM1, 
JAM2, 
JazzXx, 
JazzyY, 
joy0dat, 
joyldat, 
joytest, 
jrand4s, 

K 


KARLA, 
KBD_ADDRESETHANDLER, 
KBD_READEVENT, 
KBD_READMATRIX, 
KBD_REMRESETHANDLER, 
KBD_RESETHANDLERDONE, 
KC_NOQUAL, 
KC_VANILLA, 


KCF_ALT, 
KCE_CONTROL, 
KCF_DOWNUP, 
KCF_NOP, 
KCF_SHIFT, 
KCE_STRING, 
KEYCODE_M, 
KEYCODE_N, 
KEYCODE_Q 


oe ed 


58-109 
46-36 
46-72 
46-74 
46-70 
46-73 
46-75 
46-71 
46-25, 46-61 
48-123 
46-80 
46-78 
46-82 
46-76 
46-81 
46-79 
46-83 
46-77 
2-43, 57-34 
52-116 
52-118 
52-112 
52-114 
§2-117 
52-119 
52-113 
52-115 
52-128 
52-124 
52-126 
52-120 
52-122 


33-117, 45-63, 46-36, 52-36, 58-110 


52-129 
52-125 
§2-127 
52-121 
52-123 
52-26, 
58-111 
58-110 
58-112 
33-149 
33-416 
33-417 
33-418 
28-16 
33-150 
33-151 
33-197 
28-15 
12-42, 
12-35, 
12-46 
12-45 
12-47 


52-67 


12-47 
12-48 


12-48 
12-38 
34-187 
12-44 
6-79 
6-80 
6-77 
6-78 
12-37, 
12-43 
12-41 
28-13, 
12-40 
12-36, 
12-39 
33-112 
33-315 
34-167 
34-129 
34-1846 
34-157 
34-752 
34-750 
43-25 
33-152 
33-152 
50-88 
34-1906, 50-89 
34-87 

34-87 

13-26 

13-27 

13-47 

42-91 


12-50 


28-16 
12-51 


4-28, 4-28, 4-31, 4-31, 19-164, 19-165 


33-422 
37-19 
37-17 
37-18 
37-20 
37-21 
38-27 
38-28 
38-31 
38-33 
38-24 
38-36 
38-30 
38-32 
38-34 
38-25 
38-29 
38-37 
34-1936 
34-1935 
34-1933 
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KEYCODE_X, 
KEYDELMIC, 
KEYDELSEC, 

k a 
KEYREPMIC, 
Pecantae 
KeyRp ay, 
Key Beepeed. 
kn_H oy ikea 
km_HikeyMap, 
lon_HiKeyMap 8, 
km_HiRepeatable, 
km_Lo co 
ka_LoKeyMap, 
km_LoKeyMap 8, 
km_LoRepeatable, 
KNOBHIT, 
KNOBHMIN, 
KNOBVMIN, 
1_LockMessage, 


LACE, 
lastBlissObj, 
lastColor, 
Layer, 


Layer_Info, 
LAYERBACKDROP, 
LayerInfo, 
LayerInfo_extra, 
LayerInfo_extra_size, 
LayerLockCount, 
LayerLocker, 
LayerPtr, 
LAYERREFRESH, 
layers, 
LAYERSIMPLE, 
LAYERSMART, 
LAYERSUPER, 
ldexp, 

left, 
LEFTBORDER, 

Le ftEdge, 


LEETHIT, 

leftmost, 

LETTER, 

LIB_VECSIZE, 
LIB_VECTSIZE, 
LibNode, 
LIBRARIES_DISKFONT_H, 
LIBRARIES_DOS_H, 
LIBRARIES_DOSEXTENS_H, 
LIBRARIES_ICON_H, 
LIBRARIES_MATHFEP_H, 
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LIBRARIES_TRANSLATOR_H, 
LINEMODE, 

LinePtrn, 

linpatcnt, 

List, 

loba, 


LockCount, 
Locker, 
LockMessage, 
LockNest, 
LockPort, 
LOECprList, 
LOF list, 

at 

logl0, 
LOGHUGE, 
LOGTINY, 
LONELYMESSAGE , 
LONGINT, 
longreserved, 
LOWCHECKWIDTH, 
LOWCOMMWIDTH, 
LOWRESGADGET, 
LOWRESPICK, 
lrand48, 


Mask, 
MatchToolValue, 
matherr, 

max, 

MAXBODY, 
MAXBYTESPERROW, 
MaxChars, 
MaxCount, 
MAXCYLS, 

MAXDI SPLAYCOLUMNS, 
MAXDI SPLAYHEIGHT, 
MAXDI SPLAYROWS, 
MAXDI SPLAYWIDTH, 


34-1934 
33-252 
33-251 
10-20, 
33-250 
33-249 
34-1649 
34-1647 
38-20 
38-19 
38-18 
38-21 
38-16 
38-15 
38-14 
38-17 
34-637 
34-644 
34-646 
6-48 
60-59 
50-49 
50-46 
6-25, 6-27, 6-63, 33-135, 33-237, 33-237, 
34-231, 34-691, 34-1241, 34-1506, 39-24, 
39-25, 39-26, 50-54, 50-54 

6-52, 34-1482, 39-22 

39-19 

6-52, 34-1482 

39-39, 39-39 

39-37 

6-35 

6-53 

34-691 

39-20 

34-41 

39-16 

39-17 

39-18 

42-16, 42-93 

33-136 

34-474, 34-622 

34-74, 34-118, 34-209, 34-291, 34-742, 
34-785, 34-821, 34-1098, 34-1337, 34-1450, 
34-1555 

8-35 

50-48 

34-1763 

44-48 

15-110, 15-111, 15-112, 15-113, 15-114 
26-26, 33-72, 35-40 

16-1, 16-2 
19-4, 19-5, 
20-2, 20-3, 
29-2, 29-3, 
43-1, 43-2, 


10-53, 33-187, 33-187, 34-716, 38-13 


19-229, 
20-233 
29-44 
43-46 


20-23, 54-17, 54-19 


59-1, 59-2, 59-15 
3-59 

27-29, S0-69 
50-66 

15-64, 26-36, 
6-63 
6-31, 
6-33 
39-33 
6-46 
39-31 
6-45, 39-28 
60-48 


26-31 

42-17, 42-92 

42-18, 42-92, 43-16 
42-77 

42-78 

34-1063 

34-490, 34-706 
39-38, 50-83 
34-1879 
34-1880 
33-55 
33-48 
42-91 
14-23, 
9-93 
9-94 
9-92, 10-27 
45-38, 45-42 
61-134 
27-30, 
29-39 
42-90 
11-54, 41-4, 55-66 
34-648 

3-20 

34-676 

11-67, 50-25 
58-35 
33-406 
33-403, 
33-404 
33-405, 33-406 
16-41, 16-55 
16-23, 16-26 


26-51, 26-53, 61-62, 61-90 


39-29 


27-30, 27-30 


33-236, 50-60 


33-404 


Q, 45-54 


34-1107, 34-1415 
19-47 

45-52 

34-649 

45-50 


10-29, 10-55 
45-56 
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MaxWidth, 
MaxX 


MaxXMouse, 
MaxyY, 
MaxYMouse, 
MeMask, 
Memory, 
Menu, 
MENUCANCEL, 
MENUDOWN, 
MenuDrawn, 


MENUENABLED, 
MenuHBorder, 
MENUHOT, 
Menulten, 
MenuNanme, 
MENUNULL, 
MENUNUM, 
MENUPICK, 
MenuRPort, 
MenuSelected, 


MENUSTATE, 

MenuStrip, 

MENUTOGGLE, 

MENUTOGGLED, 
ME 


NUUP, 
MenuVBorder, 
MENUVERIFEY, 
MENUWAITING, 
Message, 


Mesetgeney: 
Micros, 
MIDRAWN, 
MIN, 
MINEREQ, 
MinHeight, 
MININT, 
MINPITCH, 
MINRATE, 
minterns, 
MINVOL, 
MinWidth, 
Minx, 
MinXMouse, 
MinyY, 
MinYMouse, 


MiscResource, 
ode, 

MODE_ 640, 
MODE_NEWEILE, 
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MODE_OLDFILE, 
Modes, 

modf, 
MOUSEBUTTONS, 
MOUSEDBLMIC, 
MOUSEDBLSEC, 
MOUSEMOVE , 
Mousex, 

MouseY, 
MouseYMininun, 
mouth_rb, 
mouths, 
mr_AllocArray, 
MR_ALLOCMI SCRESOURCE, 
MR_FREEMISCRESOURCE, 
mr_Library, 
MR_PARALLELBITS, 
MR_PARALLELPORT, 
MR_SERIALBITS, 
MR_SERIALPORT, 
mrand48, 

MSDOS1, 

MsgPort, 


MTYPE_CLOSEDOWN, 
MTYPE_DISKCHANGE, 
MTYPE_IOPROC, 
MTYPE_PSTD, 
MTYPE_TIMER, 
MTYPE_TOOLEXIT, 
MUSTDRAW, 
MutualExclude, 
N_TRACTOR, 
NABC, 

NABNC, 

NANBC, 

NANBNC, 
narrator_rb, 
NATURALE 0, 
ND_CantAlloc, 
ND_Expunged, 
ND_FreqgErr, 
ND_MakeBad, 
ND_ModeErr, 
ND_NoAudLib, 
ND_NoMen, 
ND_NoWrite, 
ND_PhonErr, 
ND_PitcheErr, 
ND_RateErr, 
ND_SexErr, 
ND_Unimp1, 
ND_UnitErr, 
ND_VolErr, 
NEWCLIPRECTS_1_1, 


34-1107, 34-1415 
25-28 

33-92 

25-28 

33-93 

24-108 
34-1829 
34-71, 34-73, 
34-1075 
34-1918 
33-94, 33-355, 33-356, 
33-359, 33-360 

34-92 

33-164, 34-1469 
34-1073 

34-82, 34-114, 34-116, 34-143 
34-80 

34-1858 

34-1845 

34-985 

33-111 

33-95, 33-362, 
33-366, 33-367 
34-1295 

34-1112 

34-165 

34-191 

34-1917 

33-163, 34-1468 
34-995 

34-1077 

2-50, 6-46, 6-48, 7-38, 7-54, 15-50, 
20-78, 20-109, 
54-22, 56-56 
34-1191 
33-90, 
34-96 
41-5, 55-67 
45-53 

34-1106, 34-1414 
19-48 

45-51 

45-49 

50-71 

45-55 

34-1106, 34-1414 
25-27 

33-92 

25-27 

33-93 

44-51 

44-51 

44-42 

33-236, 45-66 
17-14 

19-28 


34-1112 


33-357, 33-358, 


33-363, 33-364, 33-365, 


20-59, 
34-915, 45-63, 48-124, 48-138, 


34-950 
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19-24 
26-38, 
42-19, 
34-975 
33-254 
33-253 
34-977 
33-87, 
33-87, 
33-189 
45-82 
45-72 
44-44 
44-47 
44-48 
44-43 
44-38 
44-37 
44-36 
44-35 
42-91 
36-31 
6-45, 6-47, 10-33, 20-33, 20-60, 
20-79, 20-209, 20-229, 33-197, 
39-27, 39-28, 49-62, 49-82, 
61-146 

61-144 

61-147 

61-142 

61-145 

61-143 

24- 26 

34-125, 34-344 

33-292, 34-1785 

3-28, 3-34, 3-35, 3-36 
3-29, 3-34 

3-30, 3-35, 3-36 

3-31 

45-62, 45-83 

45-40, 45-43 

45-18 

45-21 

45-27 

45-16 

45-26 

45-15 

45-14 

45-20 

45-22 

45-24 

45-23 

45-25 

45-19 

45-17 

45-28 

6-68 


60-40, 
42-93 


60-52 


34-944, 34-1103, 
34-944, 34-1103, 


34-1455 
34-1455 


20-61, 
34-1190, 
54-23 
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newlayer, 

NEWLAYERINEO_CALLED, 

NEWPREES, 

NewScreen, 

NEWSIZE, 

NewWindow, 

Next, 

NextBorder, 

NextConmp, 

NextGadget, 

NextImage, 

NextItem, 

nextLine, 

NextMenu, 

NextOb, 

NextRemenmber , 

NextScreen, 

NextSelect, 

NextSeq, 

NextText, 

Next VSprite, 

NextWindow, 

nm_mnasks, 

NO_ICON_POSITION, 

NOCAREREFRESH, 

NOCONSOLE , 

NOCROSSEILL, 

Node, 

nodes, 

NOGRAPHICS, 

NOITEM, 

NOLAYERS, 

NOMENU, 

NONDP, 

NOSUB, 

NOT, 

nrand46, 

NTSC, 

NUEBS, 

NULL, 

nun, 

numchan, 

NumChars, 
NUMCYL 


NUMHEADS , 
NUMMRTYPES, 
NUMSECS, 
NUMTRACKS, 


NUMUNITS, 
nxtlist, 


QO, 
O_APPEND, 
O_CREAT, 


O_EXCL, 


O_NDELAY, 
O_RAW, 
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O_RDONLY, 
O_RDWR, 
O_TRUNC, 
O_WRONLY, 
OAlloc, 

obj, 

ObjAlloc, 

obs, 

OCTANT1, 
OCTANT 2, 
OCTANT3, 
OCTANT4, 
OCTANTS, 
OCTANT6, 
OCTANT7, 
OCTANTS , 
OFFE_DISPLAY, 
OFF_SPRITE, 
OFF_VBLANK, 
OFFSET_BEGINING, 
OFFSET_BEGINNING, 
OFESET_CURRENT, 
OFESET_END, 
OKIMATE_20, 
OlderRequest, 
O1dax 


O1ldY, 
ON_DISPLAY, 
ON_SPRITE, 
ON_VBLANK, 


ONE_DOT, 


OVELAG, 
P_STKSIZE, 
pad, 

pad2d, 
pad34, 
pad3b, 
pad7c, 
pads3, 
pads6, 
Ee 
padding, 
PAL. 
PAPERLENGTH, 
PAPERSIZE, 
PAPERTYPE, 
PAPERWIDTH, 
arallel, 
PARALLEL_PRINTER, 


33-135 

39-42 

34-997 

34-1553 

34-971 

34-1331, 61-43, 61-67 

6-61, 11-52, 11-59, 11-73, 51-14, 60-31, 60-69 
34-796 

24-189 

34-288 

34-895 

34-116 

50-44 

34-73 

24-209 

34-1827 

34-1445 

34-150 

24-193 

34-754 

24-79 

34-1095 

45-69 

61-172 

34-1302 

33-393 

50-102 

7-31, 16-51, 28-15, 61-94, 61-95, 61-96, 61-97 
7-14, 16-14, 28-9, 48-20, 49-16, 61-19 
33-386 

34-1856 

33-387 

34-1855 

42-7 

34-1857 

34-1865 

42-91 

26-59 

36-12 

24-253, 34-1909, 34-1910, 
53-15 

45-74 

34-685 

58-34, 58-35, 58-39 
58-37, 58-39 

44-40, 44-44 

58-36 

58-39 

58-40 

11-25, 11-42, 11-42 
4-27, 4-30, 19-157, 19-158 
22-11 

22-12 

22-14 

22-10 

22-16 


55-35, 55-37, 55-39 


22-6 
22-8 
22-13 
22-7 
61-135 
61-135, 61-135 
61-135 

39-26 

3-79 

3-78 

3-77 

3-76 

3-75 

3-74 

3-73 

3-72 

27-21 

27-23 

27-26 

19-41 

19-34, 19-41 

19-36 

19-38 

34-1799 

34-208 

24-92, 33-137 
24-92, 33-137 
27-20 

27-22 

27-25 

50-95 

3-63 

11-22 

33-131 

34-1269 

24-44 

42-49 

24-25 

3-64 

49-58, 49-84 
25-39, 45-75, 45-87 
13-61 
13-66 
13-70 
13-95 
13-99 
13-102 
13-104 
34-1729 
26-61 
33-294, 
33-292, 


34-1724 

34-1722 
33-295, 34-1726 
33-293 


46-85, 49-32 
34-1735 
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PARALLELNAVE , 
PARB_EOEMODE ,, 


Parent, 

ParErr_Bu fTooBig, 
ParErr_DevBusy, 
ParErr_InitErr, 
ParErr_InvParan, 
ParErr_LineErr, 
ParErr_NotOpen, 
ParErr_PortReset, 
PARE_EOEMODE, 
PARF_RAD_| BOOGIE, 
PARF_SHARED, 
~PCC_ BW, 


PCC_YMC_ BW, 
PCC_YMCB, 
vice, 
pd_Flags, 
pda_ior0O, 


iorl, 
pd_IORPort, 
crore 

re snoshat 

PA PIOR1, 
pda_Pre ferences, 


pa_PrintBu f, 

Ea pr inteltye. 

Dui cenebl es. 
pd_PWaitEnab 

pd_PWrite, 

paso, 

pd_s Rae, 

egmnentData, 

pd_SIORO, 

pd_SIOR1, 

pd_Stk, 

pd TT OR. 

Unit, 

P _ QUERY, 

PDCMD_SETPARAMS , 

PDERR_BADDIMENSION, 

PDERR_BUFEFERMEMORY , 

PDERR_CANCEL, 

PDERR_DIMENSIONOVELOW, 

PDERR_INTERNALMEMORY , 

PDERR_INVERTHAM, 

PDERR_NOTGRAPHICS, 

Close, 

ped_ColorClass, 


46-865 
46-68 
46-66 
46-64 


34-1168 


46-91 
46-90 
46-96 
46-92 
46-93 
46-94 
46-95 
46-69 
46-67 
46-65 
49-100 
49-101 
49-102 
49-103 
49-61 
49-85 
49-72, 
49-78, 
49-82 
49-70, 
49-76, 
49-86 
49-68 
49-73 
49-79 
49-87 
49-66 
49-63 
49-64 
49-88 
49-67 
49-71, 
49-77, 
49-65 
49-74 
49-80 
49-84 
49-83 
49-81 
49-62 
46-87 
46-88 
48-172 
48-175 
48-169 
48-173 
48-174 
48-171 
48-170 
49-110 
49-112 
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ped_Commands, 
ped_DoSpecial, 
ped_Expunge, 
ped_Init, 
ped_MaxColumns, 
ped_MaxXDots, 
axYDots, 
ped_NumCharSets, 
ows, 


ped_PrinterClass, 
ped_PrinterNane, 
ender, 
ped_TimeoutSecs, 
ped_XDotsInch, 
ped_YDotsInch, 
PenHeight, 

PenWidth, 

PE 2PRI, 
PF_FINE_SCROLL_MASK, 
PFA_FINE_SCROLL, 
PFB_FINE_SCROLL_SHIFT, 
PFBA, 

PL, 

PI2, 

PI4, 


itch, 

Plan Off, 
PlanePick, 
PLANEPTR, 
Planes, 
PLNCNIMSK, 
PLNCNTSHET, 
PLOSS, 
PMB_ASM, 
PMB_AWM, 
Pointer, 
PointerMatrix, 
POINTERMATRI XMINREQ, 
POINTERSIZE, 
POINTERTICKS, 
POINTERX, 
POINTERY, 
POINTREL, 
pos, 
posctldata, 
potddat, 
potidat, 
potgo, 
POTGONAME ,, 
potinp, 

pow, 


49-120 
49-121 
49-108 
49-107 
49-113 
49-116 
49-117 
49-114 
49-115 
49-109 
49-111 
49-106 
49-122 
49-123 
49-118 
49-119 
50-73 
50-72 
17-18 
17-27 
17-25 
17-26 
60-56 
14-21, 
43-13 
43-14 


33-281, 


14-21, 
42-71 
14-21 
45-65 


24-137, 
24-136, 


25-31, 
25-40 
17-15 
17-17 
42-52 
10-27, 
10-28, 


49-73, 49-74 
49-79, 49-80 


49-73 
49-79 


49-74 
49-80 


42-69, 43-11, 43-12, 43-13, 43-14 


34-1753 
42-70 


34-887 
34-887 
25-40 


10-28 
10-75 


34-1177 
34-1659 


33-36 


34-1608, 34-1659 


33-262, 


33-257 
33-258 
34-254 
13-107 
53-12 
13-30 
13-31 
13-46, 
47-7 
13-32 
42-20, 


34-1669 


47-7 
42-92 
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ow2, 

PPC_B HA, 
PPC_BWGEX, 
PPC_COLORGEX, 
PPCB_COLOR, 
PPCB_GFX, 
PPCFE_COLOR, 
PPCE_CFX, 
pr_CIS, 

vee 
pr_ConsoleTask, 
pr_Cos, 
pr_CurrentDir, 
pr_FileSystenTask, 
pr_GlobVec, 
pr_MsgPort, 
r_Pad, 
pr_PktWait, 
r_Result2, 

6 Returnaday. 
pr_SegList, 
pr_StackBase, 
pr_StackSize, 
r_Task, 
pr_TaskNun, 

Ee aeeonn. 
PRD_DUMPRPORT, 
PRD_PRTCOMMAND, 
PRD_RAWWRITE, 
PREDRAWN, 
PREF_FILE, 
Preferences, 
prefs, 

prev, 

PrevComp, 
Previten, 
PrevOb, 

PrevSeq, 
PrevVSprite, 
PRIMARY_CLIP, 
PRINTASPECT, 
PrinterData, 
PrinterExtendedData, 
PrinterFilenane, 
PrinterPort, 
PrinterSegment, 
PRINTERTYPE, 
PrintImage, 
PRINTINVERSE, 
PRINTLEFTMARGIN, 
PRINTOQUALITY. 

R j 
PRTIPERECHIMARGIN: 
PRINTSHADE, 
PRINTSPACING, 
PRINTTHRESHOLD, 
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Process, 
PROPBORDERLESS, 
PROPGADGET, 
ile rat sable 
ps_NextSegment, 
ps_PED, 
ps_Revision, 
ps_runAlert, 
peste enc 
PTermArray0, 
PTermArrayl, 
PtrHeight, 
PtrWidth, 
putc, 

utchar, 
utIcon, 
PutWBObject, 
alifier, 

Q _LP_20, 
R, 

RasInfo, 
RasPtr, 
RASSIZE, 
RastPort, 


rate, 

RAWKEY, 
RECOVERY_ALERT, 
Rectangle, 
refptr, 
REFRESHBITS, 
REFRESHWINDOW, 
Region, 
RegionRectangle, 
REL ED, 
RelLeft, 
RelTop, 
RELVERIFEY, 
RemBob, 
Remember, 
RemenmberSize, 
ReplyPort, 
REPO USE, 
REQACTIVE, 
pedo oak 
REQCLEAR , 

R unt, 

R adget, 
RegLayer, 
REQOFF W, 
ReqPad1, 
ReqPad2, 


REQSET, 
R ext, 
REQUESTDEST, 


Requester, 


42-21 

49-96 

49-97 

49-98 

49-93 

49-91 

49-94 

49-92 

20-42 

20-47 

20-44 

20-43 

20-41 

20-46 

20-37 

20-33 

20-34 

29-49 

20-40 

20-48 

20-35 

20-39 

20-36 

20-32 

20-38 

20-50 

48-33 

48-32 

48-31 

34-256 
33-298 
33-179, 33-179, 34-1631, 49-87 
33-298 

6-62, 51-14 

24-190 

33-129 

24-209 

24-194 

24-80 

7-51 

33-287, 34-1714 

49-60 

49-105, 49-131 

34-1694 

34-1639 

49-65, 49-126 

33-278, 34-1692 

394-1712 
33-286 

33-284, 
33-281, 
33-282, 
33-285, 
33-288, 
33-283, 
33-289, 


34-1704 
34-1698 
34-1700 
34-1710 
34-1716 
34-1702 
34-1718 


20-31 
34-635 
34-528 
33-124, 
49-127 
49-131 
49-130 
49-128 
49-129 
46- 26 
46-27 
34-1178 
34-1181 
$5-51, 55-52 

55-52 

29-39 

29-39 

34-929 

34-1800 

20-123 

60-42, 60-42, 60-67, 60-69 
50-31 

25-43 

6-29, 27-17, 33-111, 
34-1155, 34-1478, 
45-64 

34-989 

34-1890 

6-30, 6-65, 25-25, 51-15, 51-20 
13-40 

34-1265 

34-973 

6-49, 51-18 

51-12, 51-14, 51-21, 51-21 
33-319 

34-217 

34-217 

34-430 

24-254 

34-1825, 34-1827 

34-1828 
6-47 
34-1274 
34-264 
34-222 
34-993 
34-1128 
34-220, 
34-231 
34-262 
34-233 
34-249 
34-983 
34-224 
33-375 
34-204, 34-208, 34-1118, 34-1125 


34-551, 61-58, 61-59 


33-134, 34-37, 34-1133, 
34-1478, 48-144, 50-52 


34-514 
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REQVERIFY, 
RESCOUNT, 
reserved, 

reservedl, 
resource, 

RESOURCES_DISK_H, 
RESOURCES_MISC_H, 
RESOURCES_MISC_I, 
RESOURCES_POTGO_H, 
RESTORING, 
RETURN_ERROR, 
RETURN_FAIL, 
RETURN_OK, 


rightmost, 
RIN IGGER, 
RingXTrans, 
ae ere. 


TRAP, 
rn_ConsoleSegment, 
rn_Info, 
rn_RestartSeg, 
rn_TaskArray, 
rn_Tine, 
ROBOTICEO, 
RootNode, 

round, 

Rows, 

rp, 

Be ee yore 
_User, 

RPort, 
RWindow, 
RxOffset, 
RyOf fset, 
samp freq, 
Satis ao 
SAVEBACK, 
SAVEBOB, 
SaveBuf fer, 
SaveColor0O, 
savelayer, 
SAVEPRESERVE, 
SAVERMOUSE, 
SaveRPort, 
SAVING, 
SBitMap, 
Screen, 


SCREENDEST, 


34-991 

33-53, 33-143, 33-144, 33-144 
6-36, 6-67, 26-56, 50-84, 60-41 
6-37 

5-11, 5-12, 15-107, 44-51, 47-7 
15-2, 15-3, 15-129 

44-53 

44-1, 44-2 

A7-1, 47-2 
33-240 
19-204 
19-206 
19-200 


50-48 

24-49 

24-223 
24-223 
34-1300 
20-164 
20-167 
20-166 
20-161 
20-165 

45-41 

20-160 

43-24 

25-36 

6-29, 33-134 
39-27 

50-81 

14-24 
34-1133 
34-247 

60-71 

60-71 

45-71 

7-53 

24-24 

24-36 

24-151 
34-1503 
33-135 

24-43 

33-311 
33-234 
33-239 
33-115 
33-79, 33-84, 33-132, 33-199, 
34-1131, 34-1380, 34-1380, 
35-45, 35-50 
33-373 


33-210, 
34-1443, 34-1445, 
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ScreenTitle, 
SCREENTYPE, 
SCRGADGET, 
Scroll_X, 
Scroll1_yY, 
BREAK 


SelectFill, 
SelectRender, 
SELECTUP, 
SERB_7TWIRE, 
SERB_EOEMODE, 
SERB_PARTY_ODD, 
SERB_PARTY_ON, 
SERB_QUEVEDBRK, 
SERB_RAD_BOOGIE, 
SERB_SHARED, 
SERB_XDISABLED, 
serdat, 

serdatr, 
SerErr_BaudMismatch, 
SerErr_BufErr, 
SerErr_Bu fOver flow, 
SerErr_DetectedBreak, 
SerErr_DevBusy, 
SerErr_InitErr, 
SerErr_InvBaud, 
SerErr_InvParan, 
SerErr_LineErr, 
SerErr_NoCTS, 
SerErr_NoDSR, 
SerErr_Not ; 
SerErr_ParityErr, 
SerErr_PortReset, 
SerErr_TimerErr, 
SERF_7WIRE, 
SERF_EOFMODE, 
SERF_PARTY_ODD, 
SERE_PARTY_ON, 
SERF_QUEUEDBRK, 
SERF_RAD_BOOGIE, 
SERE_SHARED, 
SERE_XDISABLED, 
serial, 
SERIAL_PRINTER, 
SERIALNAME, 
serper, 
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34-510 
6-44 
6-44 
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52-94 
34-523 
33-64 
33-65 
34-519 
33-89, 34-950 
42-89 
34-1916 
33-128, 34-408 
34-137 
34-317 
34-1915 
52-106 
52-98 
52-108 
52-110 
52-104 
52-102 
52-100 
52-96 
13-44 
13-33 
52-132 
52-134 
52-142 
52-145 
52-131 
52-140 
52-133 
52-135 
52-136 
52-144 
52-143 
52-137 
52-139 
52-138 
52-141 
52-107 
52-99 
52-109 
52-111 
52-105 
52-103 
52-101 
52-97 
49-35, 52-147 
34-1736 
52-147 
13-45 
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SetAfPt, 
SETDITEM, 
SETDMENU, 

SetDrPt, 

SETDSUB, 

SetOPen, 
SETSITEM, 
SETSMENU, 

SETSSUB, 

setWExcept, 
SetWrMsk, 


SGR_DEFAULTBG, 
SGR_GREEN, 
SGR_GREENBG, 
SGR_ITALIC, 
SGR_MAGENTA, 
SGR_MAGENTABCG, 
SGR_NEGATIVE, 
SGR_PRIMARY, 
SGR_RED, 
SGR_REDBG, 
SGR_UNDERSCORE , 
SGR_WHITE, 
SGR_WHITEBG, 


SHADE_GREYSCALE , 


shape, 
SHARED_LOCK, 
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SHECprList, 
SHFlist, 
SHIETITEM, 
SHIFTMENU, 
SHIETSUB, 

SHIETY, 
SHOWTITLE, 
SIGBREAKB_CTRL_C, 
SIGBREAKB_CTRL_D, 
SIGBREAKB_CTRL_E, 
SIGBREAKB_CTRL_F, 
SIGBREAKE_CTRL_C, 
SIGBREAKF_CTRL_D, 
SIGBREAKF_CTRL_E, 
SIGBREAKF_CTRL_F, 
SIGN, 

SIGNELAG, 
SILENCE, 
SIMPLE_REEFRESH, 
SimpleSprite, 


SKIP_WAIT, 
sm_ArgList, 
sm_ClipID, 
sm_Message, 


g 
sn_Process, 
smn_Segnent, 

sm_ToolWindow, 
sn_Unit, 
SMART_REFRESH, 
SMARTCOMPI LER, 
sp_Msg, 
sp_Pkt, 

SPAbs, 

SPAcos, 

SPAdd, 

SPAsin, 
SPAtan, 

SPCap, 

SPCos, 

SPCosh, 

SPDiv, 
SPECIAL_ASPECT, 


9-73 
9-65 
9-74 
9-66 
9-75 
9-43 
9-53 
- 9-45 
9-55 
9-39 
9-49 
9-32 
9-42 
9-52 
9-34 
9-30 
9-38 
9-48 
9-33 
9-44 
9-54 
9-40 
9-50 
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34-1780 
34-1779 


45-86 
19-51 


60-49 
26-32 
34-1850 
34-1849 
34-1851 
33-327 
34-1530 
19-211, 
19-212, 
19-217, 
19-218, 
19-224 
19-225 
19-226 
19-227 
34-1864 
3-65 
33-216 
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53-10 
42-22, 42-94 
42-48 
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D - 105 


Apr 29 10:15 1986 h.xref Page 43 


SPECIAL_DENSITY1, 
SPECIAL_DENSITY2, 
SPECIAL_DENSITY3, 
SPECIAL_DENSITY4, 
SPECIAL_DENSITYMASK, 
SPECIAL_FRACCOLS, 
SPECIAL_FRACROWS , 
SPECIAL_FULLCOLS, 
SPECIAL_FULLROWS , 
SPECIAL_MILCOLS, 
SPECIAL_MILROWS, 
SpecialInfo, 
SpecialLink, 

SPExp, 

SPFieee, 

SPFix, 

SPFlt, 

eae 

SPLog10, 

SPMul, 

SPNeg, 
SPPow, 


spr, 
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Sprins, 
SPRITE_ATTACHED, 
Beg 
SpriteReserved, 
SPRITES, 

sprpt, 

sprRsrvd, 
sprstop, 
sprstrtup, 
SPSin, 

SPSincos, 
SPSinh, 

SPSaqrt, 

SPSub, 


SRCC, 
SRET_CANCELMENU , 
SRET_GPROP, 
SRET_GRELEASE, 
SRET_GSDRAG, 
SRET_GSIZING, 
SRET_GWDRAG, 
SRET_MENU, 
SRET_REQ, 
SRET_RJM, 


48-164 
48-165 
48-166 
48-167 
48-163 
48-160 
48-161 
48-158 
48-159 
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34-352 
34-959 
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43-42 
43-27 
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43-35 
43-32 
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SRET_SMENU, 
SRET_STRING, 
StandardPacket, 
start, 

StartMicros, 
StartSecs, 

stat, 

StateReturn, 
stderr, 

stdin, 

stdout, 

strcmp, 

STREQ, 

strequ, 

STRGADGET, 
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StringInfo, 
STRINGRIGHT, 
strlong, 
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SUD, 
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SUPER_BITMAP, 
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SuperSaveClipRects, 
SUPFRONT, 
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SUSERELAGS, 
SwapBits, 
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SWE_NOACTIVE, 
SWE_REQUEST, 

sFont, 

SYS ET, 
sGadgets, 
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SysScreen, 
system_bplcond, 
ta_Flags, 
ta_Name, 
ta_Style, 
ta_YSize, 
tan, 

tanh, 
Task, 
TBC_HCLRTAB, 
TBC_HCLRTABSALL, 
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TD_CHANGENUM, 
TD_CHANGESTATE, 
TD_FORMAT, 
TD_LABELSIZE, 
TD_LASTCOMM, 
TD_MOTOR, 
TD_NAME, 
TD_PROTSTATUS, 
TD_REMOVE, 
TD_SECSHIFET, 
TD_SECTOR, 
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timsrv, 

TINY, 
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TmpRas, 
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TOF_WaitQ, 
TOGGLESELECT, 
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1 
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26-36 

56-65 


56-62 


56-63 


56-69 


$6-75 

56-72 

56-74 
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56-68 

56-67 
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56-71 

56-59 

56-61 

56-58 
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57-26 

24-186 


31-133, 34-1647, 34-1649, 34-1651, 57-28, 57-35 


26-35 

42-76 

34-1115, 34-1369, 
42-51 

61-134 
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12-52 
25-20, 
26-53 
34-478 
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33-136 
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33-422 
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34-475, 34-623 
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34-785, 34-823, 34-1098, 34-1337, 34-1450, 
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57-39 

57-40 

59-13 

57-34 

59-12 
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50-78 
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UFB_OP, 
UEB_RA, 
UEB_WA, 
ufbfh, 
ufbflg, 

ufb j 
UNDERELOW, 
UndoBu f fer, 
UndoPos, 
union, 

Unit, 
UNIT_MICROHZ, 
UNIT_VBLANK, 
UPERONTGADGET, 
US_LEGAL, 
US_LETTER, 
UserData, 
UserPort, 
VANI LLAKEY, 
VBlank, 
vberv, 

vce fd, 

vc fddc, 

vc fde, 

vefdi, 
VetrPtr, 
VetrTbl, 
VERSIONNUMBER, 
VertBody, 
VertPot, 
vhposr, 
vhposw, 

Lew, 
ViewInitXx, 
ViewInity, 
VIEWINITYMINREQ, 
ViewLord, 
ViewModes, 
ViewPort, 


VIEWX, 
ViewXOf fset, 
VI j 
ViewYOffset, 
VIRGINDISPLAY, 
voice, 

volume, 
VP_HIDE, 

osr, 

VPOSRLOE, 
vposvy, 
VPotRes, 
VSBob, 
VSIZEBITS, 
VSIZEMASK, 
VSOVERELOW, 
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VSPRITE, 


vthick, 
VUserExt, 
VUserStuff, 
VWaitPos, 
W_TRACTOR, 
wa_Lock, 
wa_Name, 
WB_DISKMAGIC, 
WB_DISKVERSION, 


BUTE. 
WBDEVICE, 
WBDISK, 
WBDRAWER, 
WBENCHCLOSE, 
WBENCHMESSAGE, 
WBENCHOPEN, 
WBENCHSCREEN, 
WBENCHWINDOW, 
WBGARBAGE, 
WBKICK, 
WBMessage, 
WBOb ject, 
WBorBotton, 
WBorLeft, 
WBorRight, 
WBorTop, 
wbotton, 
WBPort, 
WBPROJECT, 
WBStartup, 
WBTOOt., 
WDOWNBACK, 
WDRAGGING, 
WEIRDECHO, 
wheight, 
Width, 


Window, 


WINDOWACTIVE, 
WINDOWCLOSE, 
WINDOWDEPTH, 

WINDOWDEST, 
WINDOWDRAG, 
WindowPort, 
WINDOWREFRESH, 
WINDOWSI ZING, 
WINDOWTICKED, 
WLayer, 
wo_Background, 
wo_CurrentX, 
wo_CurrentyY, 


36-19 
36-20 
36-21 
36-10 
36-8 
36-9 
42-50 
34-672 
34-683 
11-23, 


11-28, 11-33, 


31-126, 49-69, 49-75 


7-40, 48-126, 48-140 


§7-23 
57-24 
33-58 
34-1784 
34-1783 


34-356, 34-1233, 


34-1190 
34-1011 
26-39 
26-35 
14-34 
14-34 
14-34 
14-34 
50-21 
50-20 
33-26 
34-613 
34-572 
13-24 
13-42 
26-27, 
33-183, 


33-76, 
34-1685 


33-183, 34-1685 


33-31 


33-76, 35-42 


34-1561 
11-61, 


34- 1476 o 


60-47, 60-47 


33-271 
34-1681 
33-272 
34-1683 
33-320 
45-83 
45-70 
60-62 
13-23 
17-38 
13-41 
34-621 
24-122 
3-16 
3-18 
24-31 


24-23, 


24-75, 24-79, 


34-33, 


34-1510 


35-21, 35-42, 60-45 


34-1476, 60-29, 60-31, 


24-80, 24-86, 24-87, 


24-162, 24-239, 50-42 


33-138 
24-139 


24-58, 24-59, 
11-43, 


11-30, 
34-1786 
54-31 
54-32 
61-85 
61-86 


54-27, 54-30 


61-39 
61-34 
61-35 
34-1083 
34-1003 


33-198 


29-38, 33-128, 61-61, 61-93, 


33-159, 
33-156, 
33-158, 
33-157, 
33-141 
33-197 
61-37 
54-21 
61-36 
34-522 
34-518 
33-392 
33-141 


24-105, 33-136, 34-76, 


34-293, 


34-1470 
34-1470 
34-1470 
34-1470 


34-825, 


34-1555, 45-84 


6-43, 10-35, 33-78, 
34-1093, 


34-1095, 34-1168, 


61-60, 61-120 


34-1291 
34-1253 
34-1251 
33-374 
34-1249 
34-1190 
34-1308 
34-1247 
34-1312 
34-1241 
61-105 
61-121 
61-122 


24-139 
11-43 


61-98 


34-120, 
34-1100, 


34-211, 
34-1339, 34-1452, 


33-209, 34-247, 34-956, 
34-1447, 35-44, 
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wo_DefaultTool, 
wo_DrawerData, 
wo_DrawerOpen, 
wo_Flags, 
wo_FreeList, 
wo_Gadget, 
wo_IconDisp, 
wo_IconWin, 
wo_Lock, 
wo_MasterNode, 
wo_Nane, 
wo_NameX0O f fset, 
wo_NameYO f fset, 
wo_Parent, 
wo_Selected, 
wo_SelectNode, 
wo_Siblings, 
wo_StackSize, 
wo_ToolTypes, 
wo_ToolWindow, 
wo_Type, 

wo, UseCount, 
wo_UtilityNode, 
wordreserved, 
wright, 
WScreen, 
WUPERONT, 
wwidth, 


o 


Xl, 
XAccel, 
xoffset, 
XTrans, 
XVel, 


Y, 

Y1, 

YAccel, 
yoffset, 
YTrans, 
YVel, 

Zl, 

_acos, 
_asin, 
_atan, 

ed _B, 
_base, 
_BUFSIZ, 
_C, 

_cbuff, 
_cliprects, 
_CopList, 
_cos, 
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_cot, 
ctype 4 


_IOWRT, 
—L, 
_idexp, 
3109. 
logl0, 
_nodf, 
N, 
_NFILE, 
ak, 
_pl, 

2, 
izea’ 
_povw, 
_pow2, 
_ptr, 
_rcnt, 
_sin, 
_8inh, 
_8size, 
_sqrt, 
_tan, 
_tanh, 
U, 
_ViewPort, 
_went, 


o 


61-118 
61-119 
61-103 
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61-126 
61-124 
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61-120 
61-130 
61-94 
61-114 
61-115 
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61-98 
61-104 
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61-123 
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33-141 
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34-520 
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14-27 

24-221 
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24-199 

24-220 
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24-221 

33-137, 34-1184, 34-1663 

24-198 

24-220 

14-26 


50-82 


12-29, 12-45 
55-20 
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11-60 
42-11 


42-12 
42-13 
12-33, 
12-40, 
42-14 
42-15 
55-49 
55-18, 
$5-17, 
55-51, 
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55-24, 
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55-30, 
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55-29 
55-28 
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55-33 
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12-42, 
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Appendix E 


Printer Device Source Code 


This appendix contains the printer-dependent source code for the following printers: 


hpplus - Hewlett Packard LaserJet Plus 
okimate20 - Okidata 
epson - Epson X-80 series 


diablo_c - Diablo C-150 


In addition, this appendix includes the following: 
©  macros.i, which is required in order to assemble any of the “.asm”’ files 
o  prtbase.h, which contains printer data structure definitions 


o adocument called Amiga Printer Support Information, which contains additional infor- 
mation about supported printers and supported features, standard cables for printers, 
and standard switch settings for printers. 


The files in this appendix are intended to aid developers in creating their own custom printer 
drivers that can be added to the DEVS: directory on an AmigaDOS disk. The documentation 
that explains the contents of these files is in the “Printer Device” chapter of this manual. 


The sequence of linking the various files together is critical. Here is a sample command to 
ALINK that specifies the files in the correct sequence. Note that the drive specifiers given in 
this sample link command simply reflect the disks on which the various files were placed and do 
not necessarily reflect your development environment. 
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Amiga 
Printer Support 


Information 


General Information 


The Amiga printer drivers are among the most complete in the industry. We have made every effort to 
provide support for a wide variety of printers and an extensive list of features. The Preferences tool on 
your Workbench disk lists the available printers that are supported. (The default printer settings in 


Preferences are for the Epson printers.) See Jntroduction to Amiga for instructions on changing the 
Preferences settings. 


This document provides the following information: 
How to use the Preferences printer settings with the printer device 
How to use the parallel and serial devices 
How to use the printer.library routines for direct printer I/O 
How to set the standard cables and switch settings for printers 


For an unsupported printer, use the “Custom/Generic” Preferences setting. See the Amiga ROM Kernal 
Manual for instructions on constructing a custom printer driver for an unsupported printer. 


AmigaDos provides three “handlers,” or interface routines, for printer I/O: 


PAR: parallel device 
SER: serial device 
PRT: printer device 


Each of these handlers translates the device-independent file system calls, such as Write() and Open(), 


into the appropriate message traffic to the printer devices that are implemented in Exec. Exec is the 
multi-tasking kernel of the Amiga. 


The “PAR:” handler uses the “parallel.device”, which is the Exec code that manages the parallel port 
connector on the back of your Amiga. Similarly, the “SER:” handler uses the device “serial.device” to 
manage the serial port connector. Note that, aside from the baud rate setting for the serial port, the 
Preferences printer settings have no effect on the function of the PAR: and SER: handlers. The 
characters sent to the printer using these devices are not examined or converted. 


In other words, when you send output to PAR: or SER:, your application is talking straight through to the 
hardware with no intervening levels of interpretation. If you have a printer connected to your parallel 
port, escape sequences sent to PAR: will reach it directly and will have whatever effect they are defined to 
have by the printer manufacturer. 


On the other hand, the PRT: handler uses the Exec device, “printer.device.” The printer device uses the 
information it finds in the current Preferences settings to understand which kind of printer you have 
connected and how you want it to be used. The printer device can talk to either the parallel or the serial 
device, depending on the current Preferences setting. 


The following figures illustrate the difference between sending a particular escape sequence to a printer 
using the PRT: handler instead of the PAR: or SER: handlers. 


CUE 


Figure I: Printer I'O Through SER: or PAR: Handlers 








— 


The escape sequence for turning on superscripts is defined for the Epson JX-80 to be the escape 
character (ASCII code 27) plus the string, “[2u”. However, the Amiga printer-independent escape 
sequence for a superscript is “[2v”. Therefore, the printer driver for this particular printer must convert 
the latter string into the former in order for the printer to effect superscript mode. The PAR: and SER: 
handlers perform no such conversion. 


Figure 2: Printer I/O Through PRT: Handler Via Preferences Tool 


Deciding which printer handler to use depends on the nature of your application. If you use the printer 
device (PRT:), you can write code that is largely independent of the type of printer your customers have 
attached to their Amigas. This is the recommended method. 


Printing to PAR: or SER: is fairly straightforward. Keep in mind that a standard AmigaDOS text file uses 
LF (line feed) as a line separator-—not CR or CR-LF) and that a file may or may not have an LF at the 
end. You may wish to add a carriage return character to the ends of your lines of text. Or, if your printer 
offers the option, you can flip the switch that automatically gives a CR when the printer receives an LF. 


The CLI commands expect you to use the handler names as file parameters. For example, you can send 
a file to the printer with the command, 


copy myfile to prt: 


If you want to send output to the printer using the AmigaDOS file system routines directly, you must 
Open() one of the handlers and do Write() calls to it. 


Similarly, you should use the handler names with I/O to the printer from languages such as ABasiC. Note 
that--for compatability--Microsoft’s Amiga Basic defines LPT1: to be the same as PRT:. 


You can circumvent the handlers entirely and perform a direct OpenDevice() on the Exec device of 
interest to you. You then pass I/O request blocks to the device using the I/O calls provided by Exec (such 
as DoIO()). Doing so provides greater flexibility, such as allowing asynchronous I/O and setting device 
parameters (serial baud rate, for example). By using the printer.library, you have full control over the 
printer. 


Note that you must open the printer.library directly in order to use the command names instead of the 
defined escape sequences. See Table 3 for a list of the printer features and their command names. See 
the Amiga ROM Kernal Manual for more information on calling system library and device routines. 


Note the following information regarding sending I/O between the Amiga and various printers: 


Printer Device (PRT:) 


The printer device understands only its own, printer-independent, escape sequences. It converts these 
escape sequences into the printer-specific escape sequences appropriate for the printer currently selected 
in Preferences. In addition, the Initialize function (which is invoked when you open the printer device or 
when you send it the Initialize escape sequence) causes the appropriate escapes to be sent to your printer 
to configure it according to the options you have selected in Preferences. This, for example, is how your 
margin settings are sent to the printer. 


Note that, when you use the printer device, you should turn off any option on your printer that provides 
an autiomatic CR, LF, or CR-LF whenever the printer receives an LF. The printer device provides end 
of line CR-LFs as needed. 


Also keep in mind that-—-in addition to the alphanumeric printing described here--the printer device 
provides for black and white, grey-scale, and full color raster-graphics printing. This function is only 
available when your application talks directly to the printer device and not through the AmigaDOS PRT: 
handler. See the Amiga ROM Kernal Manual for an example. 


Serial and Parallel Handlers (SER:, PAR:) 


The Preferences tool printer settings have no effect on the function of the PAR: and SER: handlers (other 
than setting the baud rate used by SER:, as noted above). Any special function you want your printer to 
perform is up to you. You must choose the correct escape sequences to send, including even initialization 
functions such as the setting of margins. Clearly, you must know which printer is connected to your 
Amiga and whether it is connected to the serial or the parallel port. This is not the recommiended method 
of controlling printers. ) 


Specific serial device features (for SER:) that you cannot set in Preferences include: 
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Hardware (7-wire) or software (3-wire) handshaking 
(XON XOFF always used) 


Number of bits (8 bits always used) 
Parity (none) 


See the ROM Kernel Manual for details on setting these features. 


PRINTER.LIBRARY 


With the printer.library, you not only can send escape sequences to the printer, you can also call the 
printer-unique entry point, “PRT”. This entry point allows you to control the printer directly-—the 
necessary escape sequences will be generated for you. 


In addition, there is a printer-unique function, “RAW_WRITE” that sends characters without converting 
them. This functions the same as SER: and PAR:, except that you don’t need to know which port is 
connected to the printer. 


Types of Supported Printers 


The available printers that are supported for the Amiga include both whole character (daisy wheel) and 
dot matrix (wire, ink jet, and laser) types. As with printer capabilities, printer prices range widely, from 
just over $200 to over $3500. In general, the dot matrix printers are capable of graphics output, while 
“whole character” printers are not. 


Every attempt has been made to support a given feature on each printer that, itself, supports that feature. 
For example, the daisy wheel printers lack the capability to produce characters such as enlarged or italic 
print. Similarly, the dot matrix printers often lack such features as proportional spacing. 


None of the supported printers currently supports all of the available features. (The Epson JX-80 and the 
HP LaserJet come closest.) Whenever the system requests an unsupported feature, the PRT: handler 
simply ignores that request. (The “generic” printer driver currently ignores all feature requests.) 


If two or more features are each available for a particular printer, they should be usable in combination. 
For example, Bold—Italic-Underscore is a possible style for many printers. 


If your printer is not among those supported for the Amiga, you have two options. If your printer shares a 
number of common features with one of the supported printers, you can select that printer in Preferences. 


Keep in mind, however, that one or more of the chosen printer’s features might not produce a similar 
effect on your printer. 


Your second option is to select “Custom” from the list of supported printers in Preferences and “Generic” 
as the custom printer name. You can then construct a custom printer driver following the directions in the 
Amiga ROM Kernel Manual. 


The following table lists the printers that are currently supported for the Amiga, grouped according to 
print technology. 


Table 1: Printers Supported on the Amiga 


Dot Matrix (Wire), Parallel 


Manufacturer 


Commodore 
Epson 
Epson 
Okimate 


Daisy Wheel, Parallel 


Manufacturer 
Alphacom 
Brother 

Diablo 


Diablo 
Qume 


Ink Jet, Parallel 
Manufacturer 


Diablo 


Laser, Serial 
Manufacturer 


Hewlett Packard 
Hewlett Packard 


Other (Custom) 


Model 


CBM MPS 1000 

Epson JX-80 

Epson MX-80, FX-80, ... 
Okimate 20 


Model 

Alphapro 101 

HR-15XL 

630 (Some models are serial) 


Advantage D25 
LetterPro 20 


Model 


C-150 


Model 


Laser Jet 
Laser Jet Plus 


Limited support is offered for a “generic” printer. 


Table 2: Printer Features Supported on the Amiga 


ISO indicates that the sequence has been defined by the International Standards Organization. This is 
also very similar to ANSII x3.64. 


DEC indicates a control sequence defined by Digital Equipment Corperation. 
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Alphacom 

AlphaPro101 

Epson JX-80 

Epson X-80 

Diablo 

AdvantageD25 

HP LaserJet Plus 
CELL el [ere covert ao 


Code Description Defined 


na 


#9 Left margin set 
#0 Right margin set ea 
#8 Top margin set a 
#2 Bottom margin set oe 
[n1;n2r Top;Bottom margins DEC 


eels deeded 
[n1,n2s_Left;Right margins DEC ES 


x |x [x |x | 

#3 Clearmargins *** |X Tx Tx [x [x [x | x 
eee 
IH Sethoriz. tab ISO Tx x | TT x xk 
J Setvert.tab SO | tx tx | | | x | oT | Tt 
[0g Clear horiz.tab ISO | tx xt TE xe eT 
[39 Clear all hor. tabs ISO pfx ixixtxix | xt xtx] [Tf 
fig Clearvert. tab ISO Te 
| x | x | 


#5 Set default tabs nes 
[n"x (Extended commands) *** 


x] [x] Brother HR-15XL 
oma 
mle th CBM MPS-1000 


fad 
= 
pao 
eX 
x 
cs 
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Table 3: Printer Command Definitions 


The following table describes the supported printer functions. You can use the escape sequences with 
PRT: and the printer.library. To use the command names, open the printer.library directly. 


Again, recall that SER: and PAR: will ignore all of these and pass them directly on to the attached device. 


Cmd Escape Defined 
Name Sequence Function by:* 
aRIS ESCc reset ISO 
aRIN ESCf1 initialize ee 
aIND ESCD lf ISO 
aNEL ESCE return, lf ISO 
aRI ESCM reverse lf ISO 
aSGRO ESC(Om normal char set ISO 
aSGR3 ESC[3m italics on ISO 
aSGR23 ESC(23m italics off ISO 
aSGR4 ESC[4m underline on ISO 
aSGR24 ESC[24m underline off ISO 
aSGR1 ESC[1m boldface on ISO 
aSGR22 ESC([22m boldface off ISO 
aSFC ESC[nm (n= {30-39}) 

set foreground color ISO 
aSBC ESC[nmm (n= {40-49}) 

set background color ISO 
aSHORPO ESC[0w normal pitch DEC 
aSHORP2 ESC[2w elite on DEC 
aSHORP1 ESC[1w elite off DEC 
aSHORP4 ESC[4w condensed fine on DEC 
aSHORP3 ESC[3w condensed off DEC 
aSHORP6 ESC[6w enlarged on DEC 
aSHORPS ESC[Sw enlarged off DEC 
aDEN6 ESC[6”z shadow print on DEC (sort of) 
aDENS ESC[(5S”z shadow print off DEC 
aDEN4 ESC[4”z doublestrike on DEC 
aDEN3 ESC[3”z doublestrike off DEC 
aDEN2 ESC[2”"z NLQ on DEC 
aDEN1 ESC[1”z NLQ off DEC 
aSUS2 ESC[2v superscript on oe 
aSUS1 ESC[1v superscript off one 
aSUS4 ESC[4v subscript on ee 
aSUS3 ESC[3v subscript off ses 
aSUS0 ESC[0v normalize the line ne 
aPLU ESCL partial line up ISO 
aPLD ESCK partial line down ISO 
aFNTO ESC(B US char set DEC 
aFNT1 ESC(R French char set DEC 
aFNT2 ESC(K German char set DEC 
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aFNT3 
aFNT4 
aFNTS 
aFNT6 
aFNT7 
aFNTS8 
aFNT9 
aFNT10 
aPROP2 
aPROP1 
aPROPO 
aTSS 
aJFYS 
aJFY7 
aJFY6 
aJFYO 
aJFY3 
aJFY1 
aVERPO 
aVERP1 
aSLPP 
aPERF 
aPERFO 
aLMS 
aRMS 
aTMS 
aBMS 
aSTBM 
aSLRM 
aCAM 
aHTS 
aVTS 
aTBCO 
aTBC3 
aTBCl 
aTBC4 


aTBCALL 
aTBSALL 
aEXTEND 


* See legend for Table 2. 


ESC(A 
ESC(E 
ESC(H 
ESC(Y 
ESC(Z 
ESC(J 
ESC(6 
ESC(C 
ESC[2p 
ESC[ip 
ESC[0p 
ESC[n E 
ESC[S F 
ESC[7 F 
ESC[6 F 
ESC[0 F 
ESC[3 F 
ESC[1 F 
ESC[0z 
ESC[1iz 
ESC[nt 
ESC[ngq 
ESC[0q 
ESC#9 
ESC#0 
ESC#8 
ESC#2 


ESC([nI1;n2r 
ESC[n1;n2s 


ESC#3 
ESCH 
ESCJ 
ESC([0g 
ESC [3g 
ESC[1g 
ESC[4g 
ESC#4 
ESC#S 
ESC[n”x 


UK char set 
Danish I char set 
Swedish char set 
Italian char set 
Spanish char set 
Japanese char set 
Norweign char set 
Danish II char set 
proportional on 
proportional off 
proportional clear 
set proportional offset 
auto left justify 
auto right justify 
auto full justify 
auto justify off 
letter space (justify) 
word fill(auto center) 
1/8” line spacing 
1/6” line spacing 
set form length n 
perf skip n (n>0) 
perf skip off 

Left margin set 
Right margin set 
Top margin set 
Bottom marg set 
T&B margins 

L&R margin 

Clear margins 

Set horiz tab 

Set vertical tabs 
Clr horiz tab 

Clear all h tab 

Clr vertical tabs 

Clr all v tabs 

Clr all h & v tabs 
Set default tabs 
extended commands 


DEC 
DEC 
DEC 
DEC 
DEC 
DEC 


ee 


ISO 
ISO 
ISO 
ISO 
ISO 
ISO (special) 
ISO (special) 


eee 
ase 
DEC 
ses 
eee 
ees 
ee 
ses 


sen 


DEC 
DEC 
ISO 
ISO 
ISO 
ISO 
ISO 
ISO 


ee 
ees 


e*¢2 


Standard Cable Connections for Printers 


If you want to connect a printer to the Amiga parallel port (25 pin female) and you have an IBM PC 
parallel to Centronics (36 pin) cable, make the following 25 pin female to female cable: 


Amiga Side IBM Cable Side 
1-13 1-13 
14-16 (cut) 

17-22 17-22 
23 (cut) 

24 24 

26 connect over to 16 


Now arrange as follows: 








A'S. 












New Cable IRM Cable 





008080000090 
0000000000 OOF, 
0008000000 








Note: Don’t connect pin 14 (parallel); it causes extra line feeds on Epson printers. 


Amiga to Centronics Adapter 


Amiga Side Centronics Side 
1-13 (straight) 1-13 
14-16 (cut) 
17-22 (straight) 17-22 
23 (cut) 
24 24 
25 connect over to 16 
25 (cut) 


Table 4: Standard Switch Settings for Printers 


The standard switch settings for the Amiga supported printers are as follows: 


Alphacom AlphaPro 101 


Off On Off On 


Mode A Mode B 


|» | 


10 12 «145 
Pitch 


Brother HR-15XL 
ON 
OFF 
1234567 8 1234567 8 
SWi1 SW2 
CBM MPS-1000 


ON 
OFF unused 


123 45 67 8 
Swi SWw2 


Diablo Advantage D25 


errr 


123 45 67 8 
SW 


Diablo 630 


X X X KX K X K K 


123 45 67 8 
Swi 


Diablo C-150 


x X x X X 


123 45 67 8 
sw 


Epson LX-80 


xX X X 
xX X X XK XK 


123 45 67 8 
Swi 


Epson JX-80 


ON 
OFF 


eer 


123 45 67 8 
SW2 


aeeaseee 


12345 67 
SW2 


Xx 
X x X 


SW2 


123 45 67 8 
Swi 


ile 


Okimate 20 


(No switches available) 


Qume Letterpro 20P 


X ON x xX 
x X X X X K x OFF x x x 
123 45 67 8 123 4 5 
Swi SW2 


HP LaserJet and LaserJet Plus 


(Switches should be set to default settings: See the Owner’s Manual.) 


Appendix F 


Skeleton Device/Library Code 


This appendix contains source code for a skeleton device and a skeleton library. You can use 
this code to create your own custom devices and libraries to add to the Amiga. 
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AbortIO(), 276 
AddAnimOb(), 169 
AddBob(), 147 
AddTime(), 251 
AddVSprite(), 125 
After pointer 

changing Bob priority, 149 

in animation precedence, 172 

in Bob priority, 141-142 

in linking AnimComps, 175 
AllocMem(), 143 
AllocRaster() 

allocating memory, 29 

in saving background, 143 
Alt key, 305, 323 
Amiga keys, 292 
AndRectRegion(), 96 
Animate(), 163, 174, 177 
animation 

acceleration, 168 

AnimCRoutine, 173 

AnimORoutine, 173 

motion control, 168-169 

sequenced drawing, 166, 169 

types, 104, 105 

velocity, 168 
AnimComp 

BobComp, 145 

BOBISCOMP flag, 145 

definition, 164 

Flags variable, 173 

position, 165 

TimeSet variable, 173 
AnimCRoutine 

in creating animation, 176 

with Animate(), 177 
AnimOb 

definition, 164 

position, 165 
AnimORoutine 

in creating animation, 176 

with Animate(), 177 
AnX variable 

in ring processing, 175 

in velocity and acceleration, 168 


Index 


moving registration point, 168 
specifying registration point, 165 
Any variable 
in ring processing, 175 
in velocity and acceleration, 168 
moving registration point, 168 
specifying registration point, 165 
AOPen variable 
in filling, 37 
in RastPort, 36 
A-Pen, see FgPen 
area buffer, 41 
area pattern, 38 
AreaDraw() 
adding a vertex, 45 
in area fill, 41 
AreaEnd() 
drawing and filling shapes, 45 
in area fill, 41 
ArealInfo pointer, 41 
AreaMove() 
beginning a polygon, 45 
in area fill, 41 
AskKeyMap(), 298 
AskSoftStyle(), 199 
audio channels 
allocation, 225, 228 
allocation key, 226, 230 
changing the precedence, 231 
freeing, 230-231 
audio device 
AbortIO(), 228 
allocation/arbitration commands, 228 
BeginIO(), 228 
CloseDevice(), 228 
double-buffering, 233 
hardware control commands, 232 
IORequest block, 224 
OpenDevice(), 227 
playing the sound, 232 
precedence of users, 225 
scope of commands, 224 
starting the sound, 235 
stopping the sound, 233-234 
use of BeginIO() function, 226 
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AvailFonts(), 201 
background pen, 36 
background playfield, 31 
BDRAWN flag, 146 
beam synchronization, 58 
Before pointer 
changing Bob priority, 149 
in animation precedence, 172 
in Bob priority, 141-142 
in linking AnimComps, 175 
BeginUpdate(), 95 
BehindLayer(), 83 
BgPen, 197 
BitMap 
address, 23 
in double-buffering, 33 
in superbitmap layers, 86 
software clipping, 46 
with write mask, 42 
BitMap structure 
in dual-playfield display, 32 
preparing, 23 
bit-planes 
extracting a rectangle from, 54 
in dual-playfield display, 30 
blitter 
in Bob animation, 109 
in copying data, 57 
in disk driver, 262 
VBEAM counter, 60 
BltBitMap(), 55 
BltClear(), 50 
bltnode structure 
creating, 59 
linking blitter requests, 57 
BltPattern(), 52 
Blt Template(), 53 
BNDRYOFF macro, 46 
BobComp pointer, 145 
BOBISCOMP flag, 145 
BOBNIX flag, 146 
BOBSAWAY flag, 146 
Bobs 
adding new features, 161 
as a paintbrush, 145 
as part of AnimComp, 145 
Before, After pointers, 172 
bit-planes, 138, 140 
changing, 148 
clipping, 145 
colors, 136, 138, 140, 152 
defining, 135 
definition, 109 
displaying, 148 
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double-buffering, 146, 149 

drawing order, 141 

list, 142 

priorities, 141 

removing, 146 

saving the background, 143 

shadow mask, 139, 144 

shape, 137 

size, 136 

sorting the list, 148 

structure, 135 

transparency, 144 

troubleshooting, 153 
BORDERHIT flag, 159 
BorderLine pointer, 157 
BOTTOMHIT flag, 154 
bottommost variable 

in Bobs clipping region, 145 

in Bob/VSprite collision, 161 
B-Pen, see BgPen 
BufPath variable, 150 
BufY, BufX variables, 150 
BufBuffer variable, 150 
BWAITING flag, 145 
bytecnt variable, 53 
bytecount pointer, 50 
Caps Lock key, 291, 304 
ChangeSprite(), 112 
CheckIO(), 276, 386, 404 
cleanup variable, 60 
ClearRegion(), 96 
ClipBlit(), 55 
clipping 

in area fill, 46 

in line drawing, 44 

text, 193 
clipping rectangles 

in Bob/VSprite collision, 161 

in layer operations, 84 

in layers, 78, 94 

modifying regions, 96 
clipping region 

in Bobs, 145 

in boundary collisions, 159 

in VSprites with GELGONE, 125 
ClipRect structure, 94 
CloseDevice(), 307 
Close(), 416 
CMD_CLEAR command, 268 
CMD_UPDATE command, 268 
CMD_WRITE command, 268 
CmpTime(), 251 
collisions 

between GEL objects, 153 


boundary, 159 

boundary hits, 154 

collision mask, 156 

detection in hardware, 153 

fast detection, 157 

GEL-to-GEL, 154 

in animation, 153 

multiple, 155 

sensitive areas, 157 

user routines, 159 
CollMask variable 

in Bobs, 139 

with collision mask, 156 
color 

affect of display mode on, 6 

Bobs, 136, 152 

ColorMap structure, 24 

flickering, 134 

in dual playfield mode, 15 

in flood fill, 47 

in hold-and-modify mode, 34 

interaction between VSprites and Bobs, 152 

mode in flood fill, 47 

of individual pixel, 43 

playfield and VSprites, 134 

relationship to bit-planes, 8 

relationship to depth of BitMap, 13 

simple sprites, 111 

single-color raster, 50 

sprites, 16 

transparency, 123 

VSprite, 121, 133 
ColorMap structure, 24 
CommandTable, 436 
compF lags variable, 168 
COMPLEMENT, 197 
complement mode, 38 
ConMayGetChar(), 286 
ConPutChar(), 281 
console 

alternate key maps, 303 

capsable keys, 304 

character output, 276 

closing, 307 

control sequence introducer, 290 

control sequences, 281 

high key map, 299, 306 

input event qualifiers, 291 

input stream, 287 

keyboard input, 277 

keymapping, 292, 297 

keymapping qualifiers, 300-301 

keytypes, 302 

low key map, 299, 305 


mouse button events, 297 
raw events, 289 
raw input types, 289 
reads, 286 
repeatable keys, 305 
string output keys, 303 
window bounds, 289 
ConWrite(), 281 
cookie cut, 57 
Copper 
changing colors, 24 
display instructions, 25 
in drawing VSprites, 122 
in interlaced displays, 33 
long-frame list, 33 
MakeVPort(), 29 
MrgCop(), 25, 33 
short-frame list, 33 
user Copper lists, 61 
copying 
data, 57 
rectangles, 55 
count variable, 44 
cp_x variable 
in drawing, 42 
in text, 192 
cp_y variable 
in drawing, 42 
in text, 192 
crashing 
with drawing routines, 44 
with fill routines, 46 
CreateBehindLayer(), 81-82 
CreateExtIO(), 264, 384, 402, 417 
CreatePort(), 265, 384, 402, 417 
CreateStdIO(), 264, 279 
CreateUpFrontLayer(), 81-82 
Ctrl key, 305 
DamageList structure 
in layers, 94 
in regions, 95 
DBuffer pointer, 149 
DBufPacket structure, 150 
deallocation 
Copper list, 30 
memory, 30, 41 
DeleteExtIO(), 384, 402 
DeleteLayer(), 82 
DeletePort(), 384, 402 
DeleteStdIO(), 307 
depth, 13 
Depth variable, 136, 138 
destRastPort variable, 55 
destX variable, 55 
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dest Y variable, 55 
DHeight variable 
in ViewPort, 20 
in ViewPort display memory, 19 
diskfont library, 200 
diskfont.h, 201-202 
DisownBlitter(), 57 
display fields, 5 
display modes, lo 
display width 
affect of overscan on, 4 
effect of resolution on, 17 
DisposeRegion(), 96 
DMA 
displaying the View, 25 
playfield, 13 
DoCollision() 
purpose, 153 
with collision masks, 160 
DolIO(), 276 
DoSpecial(), 435-437 
dotted lines, 38 
double-buffering 
allocations for, 32 
Copper in, 33 
Copper lists, 128 
with Bobs, 149 
DrawerData structure, 482 
Draw() 
in line drawing, 43 
multiple line drawing, 44 
DrawGList() 
and BDRAWN flag, 146 
and BOBNIX flag, 146 
and BOBSAWAY flag, 146 
and BWAITING flag, 145 
animation, 163 
changing Bobs, 149 
displaying Bobs, 148 
linking AnimComps, 175 
moving registration point, 168 
preparing the GELS list, 127 
removing Bobs, 147 
with DoCollision(), 177 
drawing 
changing part of drawing area, 52 
clearing memory, 50 
colors, 37 
complement mode, 38 
lines, 43 
memory for, 35 
modes, 37-38 
moving source to destination, 53 
pens, 36-37 
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pixels, 43 

shapes, 47 

turning off outline, 46 
drawing pens 

color, 37 

current position, 42 
Draw Mode variable 

in area drawing and filling, 45 

in flood fill, 48 

in stencil drawing, 52 

with BltTemplate, 55 

in text, 197 
dual playfields 

bit-planes, 31 

color map, 24 

colors, 15 

priority, 31 
DUALPF flag 

in dual playfield display, 31 

in ViewPort, 15 
DumpRPort(), 415, 423 
DWidth variable 

in ViewPort, 12-13, 20 

in ViewPort display memory, 19 
Dx Offset variable 

effect on display window, 20 

in ViewPort display memory, 19 
Dy Offset variable 

effect on display window, 20 

in ViewPort display memory, 19 
EndUpdate(), 95 
EQUAL status code, 59 
ETD_CLEAR command, 268 
ETD_MOTOR command, 268 
ETD_READ command, 267 
ETD_UPDATE command, 268 
ETD_WRITE command, 268 
EXTRA_HALFBRITE flag, 15-16 
fast floating-point hbrary, 453 
FattenLayerInfo(), 80 
FgPen variable 

in area drawing and filling, 45 

in complement mode, 38 

in flood fill, 47-48 

in JAM1 mode, 37 

in line drawing, 44 

in RastPort, 36 

in rectangle fill, 48 

in text, 197 

with BltTemplate, 55 
FindToolType(), 487 
Flags variable 

in AnimComps, 173 

in layers, 85 


in VSprites, 124 

with BNDRYOFF macro, 46 
flicker, 58, 60 
Flood(), 47 
floppy disk, 262 
FontContents structure, 201 
FontContentsHeader structure, 201 
fonts, 192 
Forbid(), 487 
foreground pen, 36 
FOREVER loop, 29 
FreeColorMap(), 29 
FreeCprList(), 29 
FreeDiskObject(), 481 
FreeRaster(), 29 
FreeSprite(), 120 
FreeVPortCopLists(), 29 
Gadget structure, 483 
gameport connectors, 322 
gameport device 

connectors, 345 

system functions, 346 

triggering events, 348 

units, 322, 345 
gameport.h, 348 
GameTrigger structure, 348 
GELGONE flag 

in Bobs, 145 

with VSprites, 125 
GELS 

initializing, 106 

list, 106 

types, 107 
GelsInfo pointer, 42 
GelsInfo structure, 131 
GetColorMap(), 29 
GetDisk Object(), 481 
GetMsg(), 386, 404 
GetSprite(), 111 
GfxBase variable, 22 
GPD_GETCTYPE command, 347 
GPD_SETCTYPE command, 346 
GPD_SETTRIGGER command, 348 
graphics library, 22 
HAM flag, 15, 34 
hardware sprites 

allocation, 111 

in animation, 25 

reserving, 131 
Height variable 

in Bobs, 136, 138 

in ViewPort, 12 

in VSprites, 121 
HIRES flag, 15 


HitMask variable, 159 
hold-and-modify mode, 34 
icon library, 480 
IDCMP, 327 
ImageData pointer 
changing Bobs, 148 
changing VSprites, 129 
in Bobs, 137 
in VSprites, 122-123 
Image structure, 484 
ImageShadow variable 
in Bobs, 139 
with OVERLAY flag, 144 
IND_ADDHANDLER command, 324 
IND_REMHANDLER command, 326 
IND_SETPERIOD command, 327 
IND_SETTHRESH command, 327 
IND_WRITEEVENT command, 326 
info file, 481 
InitArea(), 41 
InitGels(), 106 
InitLayers(), 80 
InitMasks() 
changing Bob image shadow, 148 
defining collision mask, 156 
with Borderline, 158 
InitRastPort(), 196 
input device 
adding a handler, 324 
and console device, 323 
commands, 323 
designing an input handler, 324 
generating input events, 326 
TOStdReq block, 324 
key repeat events, 327 
memory deallocation, 325 
opening, 322 
removing a handler, 326 
setting key repeat interval, 327 
setting key repeat timing, 327 
input event chain, 325 
input event structure, 323 
input events 
generators of, 326 
Intuition handling of, 324 
mouse button, 328 
inputevent.h, 323 
input_request_block, 326 
Intuition 
as input device handler, 324 
mouse input, 322 
with sprites, 110 
INVERSEVID mode 


in drawing, 38 
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in text, 198 
IODRPRegq structure, 416 
IOExtPar structure, 403 
IOExtSer structure, 385, 396 
IOExtTD structure, 265 
IOPrtCmdReg structure, 416 
IOStdReq structure, 279 
io_TermArray, 388, 405 
JAM1 mode 

in drawing, 37 

in text, 197 

with INVERSEVID, 38 
JAM2 mode 

in drawing, 37 

in text, 197 
joystick controller, 347 
KBD_ADDRESETHANDLER command, 339 
KBD_READEVENT command, 341 
KBD_READMATRIX command, 340 
KBD_REMRESETHANDLER command, 340 
KBD_RESETHANDLERDONE command, 340 
keyboard device 

keyboard events, 337 

system functions, 338 
keyboard layout, 292 
KeyMap structure, 298 
keymap.h, 301 
keymap.1, 301 
LACE flag 

in View and ViewPort, 18 

in ViewPort, 15 
layer refresh 

simple refresh, 85 

smart refresh, 86 

superbitmap, 86 
LAYERBACKDROP flag, 86 
Layer_Info structure, 80, 88 
layers 

accessing, 81 

backdrop, 86 

blocking output, 81 

clipping rectangle list, 94 

creating, 81-82, 88 

creating the workspace, 88 

deleting, 82 

moving, 82 

order, 83 

redrawing, 95 

scrolling, 83 

simple refresh, 94 

sizing, 82 

sub-layer operations, 84 

updating, 95 
layers library 
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contents, 77 

opening, 87 
LAYERSIMPLE flag, 85 
LAYERSMART flag, 85 
LAYERSUPER flag, 85 
LEFTHIT flag, 154 
leftmost variable 

in Bobs clipping region, 145 

in Bob/VSprite collision, 161 
line drawing, 43 
line pattern, 38 
LinePtrn variable, 45 
lines 

multiple, 44 

patterned, 44 
LoadRGBA(), 24 
LoadView() 

effect of freeing memory, 30 

in display ViewPorts, 25 
Locklayer(), 81 
LockLayerInfo(), 81 
LockLayers(), 81 
LOFCprList variable, 33 
logic equations, 56 
long-frame Copper list, 33 
MakeView() 

with simple sprites, 110 
MakeVPort() 

allocating memory, 29 

in double-buffering, 33 

in dual playfield display, 31 
Mask variable, 42, 55 
MatchToolValue(), 488 
math library, 453 
mathffp library, 455 
mathieeedoubbas_lib.lib, 474 
mathieeedoubbas. library, 472 
mathlink.ltb, 457, 464 
mathtrans.library, 461 
maxx variable, 52 
maxy variable, 53 
MeMask variable, 159 
memblock pointer, 50 
memory 

allocation for BitMap, 23 

clearing, 50 

deallocation of, 41 

for area fill, 41 

freeing, 29 
MICROHZ timer unit, 248 
minterm variable, 56 
Modes variable 

in View structure, 20 

in ViewPort, 14-15 


modulo, 54 
mouse button, 323 
mouse button events, 297, 322 
mouse controller, 347 
mouse movement events, 322 
mouth structure, 365 
Move(), 43, 192 
MoveLayer(), 82 
MoveSprite(), 113 
MrgCop() 
in graphics display, 25 
installing VSprites, 128 
merging Copper lists, 30 
myInfo structure, 162 
narrator device 
Arpabet, 373 
consonants, 374 
content words, 376 
contractions, 374 
controlling speech characteristics, 364 
function words, 376 
improving intelligibility, 378 
mouth shape, 365 
opening, 363 
opening the device, 366 
output buffer, 362 
phonemes, 373 
phonetic spelling, 373 
punctuating phonetic strings, 372 
punctuation, 377 
reading and writing, 366 
recommended stress values, 376 
special symbols, 375 
speech synthesis system, 379 
stress and intonation, 375 
stress marks, 375 
translator library, 362 
vowels, 373 
narrator.h, 365 
narrator.t, 365 
narrator_rb structure, 364 
NewLayerInfo(), 80 
NewRegion(), 95 
New Window structure, 482 
NextComp pointer 
in linking AnimComps, 175 
in sequenced drawing, 171 
Next variable, 22 
NextSeq pointer 
in linking AnimComps, 175 
in sequenced drawing, 170 
NOTEQUAL status code, 59 
ON_DISPLAY macro, 127 
ON_SPRITE macro, 127 


O-Pen, see AOIPen 
OpenConsole(), 278 
OpenDiskFont(), 195, 205 
OpenFont(), 195, 205 
Open(), 416 
OpenScreen(), 110 
OrRectRegion(), 96 
outline mode, 47 
outline pen, 36 
OVERLAY flag, 144 
OwnBlitter(), 57 
PAR:, 414 
parallel device 
closing, 408 
EOF mode, 405-406 
errors, 407 
flags, 406 
IOExtPar block, 403 
io_TermArray, 405-406 
loading from disk, 402 
opening, 402 
opening timer device, 403 
PDCMD_SETPARAMS, 403 
reading, 403, 404 
setting parameters, 403, 406-407 
shared access, 406 
terminating the read, 405 
termination characters, 406 
writing, 405 
PDCMD_SETPARAMS, 403 
PED structure, 428 
PFBA flag 
in dual playfield mode, 17 
in ViewPort, 15 
pixel width, 17 
PlaneOnOff variable 
changing Bob color, 149 
in Bobs, 140 
PlanePick variable 
changing Bob color, 149 
in Bobs, 138, 140-141 
PLANEPTR, 23 
PolyDraw(), 44 
polygons, 45 
power_of_two variable, 38 
PRD_DUMPRPORT, 423 
PRD_PRTCOMMAND, 422 
Preferences, 415, 428 
PrevComp pointer 
in linking AnimComps, 179 
in sequenced drawing, 171 
PrevSeq pointer 
in linking AnimComps, 175 
in sequenced drawing, 170 
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PrintCommand(), 422 
printer device 
alphanumeric drivers, 435 
buffer deallocation, 434 
buffer space, 432 
closing DOS printer device, 416 
command buffer, 432 
command functions, 419 
CommandTable, 435 
creating an I/O request, 417 
creating drivers, 428 
data structures, 416 
density, 434 
direct use, 415 
DOS parallel device, 414 
DOS printer device, 414 
DOS serial device, 414 
double buffering, 433 
dumping a RastPort, 423 
dumping buffer, 433 
Exec printer I/O, 416 
graphics printer drivers, 431 
opening, 418 
opening DOS printer device, 415 
output forms, 414 
output methods, 413 
PAR:, 414 
Preferences, 415, 428, 430, 437 
printer types, 431 
processes and tasks, 416 
PRT:, 414, 419 
reset command, 433 
SER:, 414 
timeout, 430 
transmitting commands, 422 
writing, 418 
PrinterData structure, 430 
PrinterExtendedData structure, 428 
printerlO structure, 416 
PRT:, 414 
PutDiskObject(), 481 
PWait(), 433 
QBlit() 
linking bltnodes, 58 
waiting for the blitter, 57 
QBSBIlit() 
avoiding flicker, 58 
linking bltnodes, 58 
waiting for the blitter, 57 
QueueRead(), 286 
RasInfo structure, 20 
RASSIZE macro, 21 
raster 
depth, 13 
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dimensions, 19 
in dual-playfield mode, 15 
memory allocation, 21 
one color, 50 
RasInfo structure, 20 
scrolling, 51 
RastPort 
in area fill, 41 
in layers, 84 
pointer to, 42 
RastPort structure, 192 
rastport variable, 52 
rastport.h, 36 
rastport.1, 36 
Raw Write(), 415 
ReadPixel(), 43 
rectangle fill, 48 
rectangle scrolling, 51 
RectFill(), 48 
regions 
changing, 96 
clearing, 96 
creating, 95 
removing, 96 
registration point, 168 
RemBob(), 147 
RemIBob(), 147 
Remove(), 386, 404 
RemVSprite(), 125-126 
Render{(), 431 
ReplyPort, 279 
Reply Port pointer, 249 
RHeight, 19 
RIGHTHIT flag, 154 
rightmost variable 
in Bobs clipping region, 145 
in Bob/VSprite collision, 161 
RINGTRIGGER flag 
in AnimComps, 173 
in linking AnimComps, 175 
moving registration point, 168 
RingX Trans variable 
in ring processing, 175 
moving registration point, 168 
Ring Y Trans variable 
in ring processing, 175 
moving registration point, 168 
RWidth, 19 
RxOffset variable 
effect on display, 20 
in RasInfo structure, 20 
in ViewPort display memory, 19 
Ry Offset variable 
effect on display, 20 


in RasInfo structure, 20 
in ViewPort display memory, 19 
SAVEBACK flag 
in Bobs, 144 
saving the background, 143 
SAVEBOB flag 
changing Bobs, 149 
in Bobs, 145 
SaveBuffer variable 
in saving background, 143 
with SAVEBACK, 144 
SAVEPRESERVE flag, 146 
scrolling, 51 
ScrollLayer(), 83, 86 
ScrollRaster(), 51 
SDCMD_SETPARAMS, 385 
SendIO(), 276 
SER:, 414 
serial device 
alternative reading modes, 386-387 
baud rate, 390 
bits per read, 391 
bits per write, 391 
break commands, 393 
break conditions, 391 
buffer size, 390 
buffers, 385 
closing, 394 
end-of-file, 391 
EOF mode, 388, 391 
errors, 394 
exclusive access, 384 
flags, 384 
high-speed mode, 391 
I/O request structures, 385 
IOExtSer block, 396 
io_TermArray, 388 
modes, 383 
opening timer device, 385 
parameter changes, 385 
parity, 393 
quick I/O, 387 
reading, 385 
SDCMD_SETPARAMS, 385 
serial flags, 391 
seven-wire access, 393 
seven-wire flag, 384 
shared access, 384, 391 
stop bits, 391 
terminating the read, 388 
writing, 388 
xON, xOFF, 390-391 
SetAPen(), 197 
SetBPen(), 197 


SetCollision(), 155 
SetDrPt(), 44 
SetFont(), 195 
SetKeyMap(), 298 
SetRast(), 50 
SetSoftStyle(), 199 
SHFCprlist variable, 33 
short-frame Copper list, 33 
simple refresh, 94 
simple sprites 

definition, 108 

GfxBase, 131 

in Intuition, 110 

position, 113 

routines, 110 
SimpleSprite structure, 112 
single-buffering, 21 
SizeLayer(), 82, 86 
software clipping 

in filling, 46 

in line drawing, 44 
SortGList() 

changing Bobs, 149 

ordering GEL list, 126 

sorting Bobs, 148 

with DoCollision(), 177 
sound synthesis, 222 
source variable, 55 
speech, see narrator device 
SprColors pointer 

changing VSprites, 129 

in VSprite troubleshooting, 132 

in VSprites, 122-123 

when a 0, 133 
sprF lag variable, 143 
sprite DMA, 132 
SPRITE flag, 110 
sprites 

color, 16, 111 

display, 13 

hardware, 108 

pairs, 111 

reserving, 131 

reusability, 108 

simple, 108 

virtual, 108 
sprRsrvd variable 

effect on Bob color, 153 

in reserving sprites, 131 
srcMod variable, 55 
srcX variable, 55 
stencil drawing, 52 
SubTime(), 251 
SwapBitsClipRectRastPort(), 84 
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system time, 201 
TD_CHANGENUM command, 269 
TD_CHANGESTATE command, 270 
TD_FORMAT command, 269 
TD_MOTOR command, 268 
TD_PROTSTATUS command, 270 
TD_REMOVE command, 269 
TD_SEEK command, 270 
text 

adding fonts, 200 

baseline, 193 

changing font style, 199 

character data, 206 

color, 197 

default fonts, 195 

defining fonts, 203 

disk fonts, 202 

font accessors, 205 

inter-character spacing, 200 

printing, 194 

selecting a font, 195 
TextAttr structure, 195 
TextFont structure, 203 
Text(), 194, 199 
text.h, 195 
ThinLayerInfo(), 80 
time events, 322 
timer device 

arithmetic routines, 253 

OpenDevice(), 249 

units, 248 

with parallel device, 403 

with serial device, 385 
TimerBase variable, 253 
timeRequest structure, 248 
Timer variable, 174 
TimeSet variable 

with Animate(), 174 
timeval structure, 248 
ToolTypes array, 487 
TOPHIT flag, 154 
topmost variable 

in Bobs clipping region, 145 

in Bob/VSprite collision, 161 
trackdisk device 

diagnostic commands, 270 

error codes, 270 

OpenDevice(), 266 

status commands, 269 
Translate(), 362 
translator library 

exception table, 363 
TR_GETSYSTIME, 251 
TR_GETSYSTIME command, 251 
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TR_SETSYSTIME command, 251 
Unlocklayer(), 81 
UnlockLayers(), 81 
UpfrontLayer(), 83 
user copper lists, 61 
UserExt variable, 161 
UserStuff variables, 162 
VBEAM counter, 60 
VBLANK < timer unit, 248 
video priority 

Bobs, 105 

in dual-playfield mode, 15 
View structure 

Copper lists in, 33 

function, 10 

preparing, 22 
ViewPort 

colors, 13, 24 

display instructions, 25 

display memory, 19 

displaying, 11 

function, 10 

height, 12 

in screens, 11 

interlaced, 18 

low-resolution, 22 

modes, 14-15 

multiple, 22 

parameters, 12 

width, 13 

width of and sprite display, 13 

windows, 11 
ViewPort structure, 22 
VP_HIDE flag, 16 
VSOVERFLOW flag 

reserving sprites, 131 

with VSprites, 125 
VSPRITE flag 

in Bobs, 144 

in VSprites, 125 
VSprites 

adding new features, 161 

building the Copper list, 127 

changing, 129 

color, 121 

colors, 133 

definition, 108 

dummy, 106 

hardware sprite assignment, 126, 132 

in Intuition, 124 

merging instructions, 128 

playfield colors, 134 

position, 124 

shape, 122 


size, 121 
sorting the GEL list, 126 
troubleshooting, 132 
turning on the display, 127 
Wait TOF(), 129 
WhichLayer(), 83 
Width variable, 136 
Window structure, 275 
Workbench 
info file, 481 
sample startup program, 489 
start-up code, 486 
start-up message, 485-486 
ToolTypes, 487 
Workbench object, 480 
WritePixel(), 43 
XAccel variable, 168 
xl variable, 52 
xmax variable, 48 
xmin variable, 48 
XorRectRegion(), 96 
X Trans, 166 
XVel variable, 168 
YAccel variable, 168 
yl variable, 53 
ymax variable, 48 
ymin variable, 48 
Y Trans, 166 
YVel variable, 168 
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